diff options
author | joerg <joerg@FreeBSD.org> | 1996-03-31 22:36:14 +0000 |
---|---|---|
committer | joerg <joerg@FreeBSD.org> | 1996-03-31 22:36:14 +0000 |
commit | 9fb42bdd3bddec23fe01cde7bfb9219b599da34d (patch) | |
tree | bb05b6399b5d4ba99adb8a50156f541e24cf5fac /share/man | |
parent | a8d7ddd754512c7f6ee090f132ba679f81b8e14a (diff) | |
download | FreeBSD-src-9fb42bdd3bddec23fe01cde7bfb9219b599da34d.zip FreeBSD-src-9fb42bdd3bddec23fe01cde7bfb9219b599da34d.tar.gz |
Convert this to a real man page. Using one blurb of a .Bd -literal
looks rather ugly.
Also slightly adopt the contents to the results of a discussion that
took place in -core some months ago. We couldn't agree on everything,
but some of the previous sentiments were rather outdated.
Diffstat (limited to 'share/man')
-rw-r--r-- | share/man/man9/style.9 | 400 |
1 files changed, 231 insertions, 169 deletions
diff --git a/share/man/man9/style.9 b/share/man/man9/style.9 index ffd71c4..2e59b79 100644 --- a/share/man/man9/style.9 +++ b/share/man/man9/style.9 @@ -7,14 +7,13 @@ .Sh DESCRIPTION This file contains an example of the preferred style for kernel source files in the FreeBSD source tree. -.in 0 -.Bd -literal +.Bd -literal -offset 0i /* * Style guide for the 4BSD KNF (Kernel Normal Form). * * @(#)style 1.14 (Berkeley) 4/28/95 * - * FreeBSD $Id: style.9,v 1.3 1995/12/21 18:35:19 phk Exp $ + * FreeBSD $Id: style.9,v 1.4 1996/02/09 16:20:10 mpp Exp $ * */ @@ -28,62 +27,71 @@ files in the FreeBSD source tree. * Multi-line comments look like this. Make them real sentences. Fill * them so they look like real paragraphs. */ - -/* - * Kernel include files come first; normally, you'll need <sys/types.h> - * OR <sys/param.h>, but not both! <sys/types.h> includes <sys/cdefs.h>, - * and it's okay to depend on that. - */ +.Ed +.Pp +Kernel include files come first; normally, you'll need <sys/types.h> +OR <sys/param.h>, but not both! <sys/types.h> includes <sys/cdefs.h>, +and it's okay to depend on that. +.Bd -literal -offset 0i #include <sys/types.h> /* Non-local includes in brackets. */ - -/* If it's a network program, put the network include files next. */ +.Ed +.Pp +If it's a network program, put the network include files next. +.Bd -literal -offset 0i #include <net/if.h> #include <net/if_dl.h> #include <net/route.h> #include <netinet/in.h> #include <protocols/rwhod.h> - -/* - * Then there's a blank line, followed by the /usr include files. - * The /usr include files should be sorted! - */ +.Ed +.Pp +Then there's a blank line, followed by the /usr include files. +The /usr include files should be sorted! +.Bd -literal -offset 0i #include <stdio.h> - -/* - * Global pathnames are defined in /usr/include/paths.h. Pathnames local - * to the program go in pathnames.h in the local directory. - */ +.Ed +.Pp +Global pathnames are defined in /usr/include/paths.h. Pathnames local +to the program go in pathnames.h in the local directory. +.Bd -literal -offset 0i #include <paths.h> - -/* Then, there's a blank line, and the user include files. */ +.Ed +.Pp +Then, there's a blank line, and the user include files. +.Bd -literal -offset 0i #include "pathnames.h" /* Local includes in double quotes. */ - -/* - * Macros are capitalized, parenthesized, and should avoid side-effects. - * If they are an inline expansion of a function, the function is defined - * all in lowercase, the macro has the same name all in uppercase. If the - * macro needs more than a single line, use braces. Right-justify the - * backslashes, it makes it easier to read. - */ +.Ed +.Pp +Macros are capitalized, parenthesized, and should avoid side-effects. +If they are an inline expansion of a function, the function is defined +all in lowercase, the macro has the same name all in uppercase. If the +macro needs more than a single line, use braces. Right-justify the +backslashes, it makes it easier to read. +.Bd -literal -offset 0i #define MACRO(x, y) { \e variable = (x) + (y); \e (y) += 2; \e } - -/* Enum types are capitalized. */ +.Ed +.Pp +Enum types are capitalized. +.Bd -literal -offset 0i enum enumtype { ONE, TWO } et; - -/* - * When declaring variables in structures, declare them sorted by use, then - * by size, and then by alphabetical order. The first category normally - * doesn't apply, but there are exceptions. Each one gets its own line. - * Put a tab after the first word, i.e. use "int^Ix;" and "struct^Ifoo *x;". - * - * Major structures should be declared at the top of the file in which they - * are used, or in separate header files, if they are used in multiple - * source files. Use of the structures should be by separate declarations - * and should be "extern" if they are declared in a header file. - */ +.Ed +.Pp +When declaring variables in structures, declare them sorted by use, then +by size, and then by alphabetical order. The first category normally +doesn't apply, but there are exceptions. Each one gets its own line. +Put a tab after the first word, i.e. use +.Ql int^Ix; +and +.Ql struct^Ifoo *x; . +.Pp +Major structures should be declared at the top of the file in which they +are used, or in separate header files, if they are used in multiple +source files. Use of the structures should be by separate declarations +and should be "extern" if they are declared in a header file. +.Bd -literal -offset 0i struct foo { struct foo *next; /* List of active foo */ struct mumble amumble; /* Comment for mumble */ @@ -95,28 +103,35 @@ struct foo *foohead; /* Head of global foo list */ typedef struct _bar { int level; } BAR; +.Ed +.Pp +All functions are prototyped somewhere. +.Pp +Function prototypes for private functions (i.e. functions not used +elsewhere) go at the top of the first source module. Functions +local to one source module should be declared +.Ql static . +.Pp +Functions used from other parts of the kernel are prototyped in the +relevant include file. +.Pp +Functions that are used locally in more than one module go into a +separate header file, e.g. +.Pa extern.h . +.Pp +Only use the __P macro from the include file <sys/cdefs.h> if the source +file in general is (to be) compilable with a K&R Old testament compiler. +.Pp +Only the kernel has a name associated with the types, i.e. in the kernel +use: +.Bd -literal -offset 0i +void function __P((int fd)); +.Ed +.Pp +in user land use: +.Bd -literal -offset 0i + void function __P((int)); -/* - * All functions are prototyped somewhere. - * - * Function prototypes for private functions (i.e. functions not used - * elsewhere) go at the top of the first source module. - * - * Functions used from other parts of the kernel are prototyped in the - * relevant include file. - * - * Only use the __P macro from the include file <sys/cdefs.h> if the source - * file in general is (to be) compilable with a K&R Old testament compiler. - * - * Only the kernel has a name associated with the types, i.e. in the kernel - * use: - * - * void function __P((int fd)); - * - * in user land use: - * - * void function __P((int)); - */ static char *function __P((int, const char *)); static void usage __P((void)); @@ -136,14 +151,15 @@ main(argc, argv) int ch; char *ep; - /* - * For consistency, getopt should be used to parse options. Options - * should be sorted in the getopt call and the switch statement, unless - * parts of the switch cascade. Elements in a switch statement that - * cascade should have a FALLTHROUGH comment. Numerical arguments - * should be checked for accuracy. Code that cannot be reached should - * have a NOTREACHED comment. - */ +.Ed +.Pp +For consistency, getopt should be used to parse options. Options +should be sorted in the getopt call and the switch statement, unless +parts of the switch cascade. Elements in a switch statement that +cascade should have a FALLTHROUGH comment. Numerical arguments +should be checked for accuracy. Code that cannot be reached should +have a NOTREACHED comment. +.Bd -literal -offset 0i while ((ch = getopt(argc, argv, "abn")) != EOF) switch (ch) { /* Indent the switch. */ case 'a': /* Don't indent the case. */ @@ -165,35 +181,39 @@ main(argc, argv) argc -= optind; argv += optind; - /* - * Space after keywords (while, for, return, switch). No braces are - * used for control statements with zero or only a single statement. - * - * Forever loops are done with for's, not while's. - */ +.Ed +.Pp +Space after keywords (while, for, return, switch). No braces are +used for control statements with zero or only a single statement. +.Pp +Forever loops are done with for's, not while's. +.Bd -literal -offset 0i for (p = buf; *p != '\e0'; ++p); for (;;) stmt; - /* - * Parts of a for loop may be left empty. Don't put declarations - * inside blocks unless the routine is unusually complicated. - */ +.Ed +.Pp +Parts of a for loop may be left empty. Don't put declarations +inside blocks unless the routine is unusually complicated. +.Bd -literal -offset 0i for (; cnt < 15; cnt++) { stmt1; stmt2; } - - /* Second level indents are four spaces. */ +.Ed +.Pp +Second level indents are four spaces. +.Bd -literal -offset 0i while (cnt < 20) - z = a + really + long + statment + that + needs + two lines + - gets + indented + four + spaces + on + the + second + - and + subsequent + lines. - - /* - * Closing and opening braces go on the same line as the else. - * Don't add braces that aren't necessary. - */ + z = a + really + long + statment + that + needs + + two lines + gets + indented + four + spaces + + on + the + second + and + subsequent + lines. +.Ed +.Pp +Closing and opening braces go on the same line as the else. +Don't add braces that aren't necessary. +.Bd -literal -offset 0i if (test) stmt; else if (bar) { @@ -201,91 +221,114 @@ main(argc, argv) stmt; } else stmt; - - /* No spaces after function names. */ +.Ed +.Pp +No spaces after function names. +.Bd -literal -offset 0i if (error = function(a1, a2)) exit(error); - - /* - * Unary operators don't require spaces, binary operators do. Don't - * use parenthesis unless they're required for precedence, or the - * statement is really confusing without them. - */ +.Ed +.Pp +Unary operators don't require spaces, binary operators do. Don't +use parenthesis unless they're required for precedence, or the +statement is really confusing without them. +.Bd -literal -offset 0i a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; k = !(l & FLAGS); - - /* - * Exits should be 0 on success, and 1 on failure. Don't denote - * all the possible exit points, using the integers 1 through 300. - */ - exit(0); /* Avoid obvious comments such as "Exit 0 on success." */ +.Ed +.Pp +Exits should be 0 on success, or according to the predefined +values in +.Xr sysexits 3 . +.Bd -literal -offset 0i + exit(EX_OK); /* + * Avoid obvious comments such as + * "Exit 0 on success." + */ } - -/* - * If a function type is declared, it should be on a line - * by itself preceeding the function. - */ +.Ed +.Pp +The function type should be on a line by itself +preceeding the function. +.Bd -literal -offset 0i static char * function(a1, a2, fl, a4) int a1, a2, a4; /* Declare ints, too, don't default them. */ float fl; /* List in order declared, as much as possible. */ { - /* - * When declaring variables in functions declare them sorted by size, - * then in alphabetical order; multiple ones per line are okay. Old - * style function declarations can go on the same line. ANSI style - * function declarations should go in the include file "extern.h". - * If a line overflows reuse the type keyword. - * - * DO NOT initialize variables in the declarations. - */ +.Ed +.Pp +When declaring variables in functions declare them sorted by size, +then in alphabetical order; multiple ones per line are okay. +Declaring functions inside functions is not recommendable, since their +linkage scope is always global. If a line overflows reuse the type +keyword. +.Pp +Be careful to not obfuscate the code by initializing variables in +the declarations. Use this feature only thoughtfully. +.Bd -literal -offset 0i extern u_char one; extern char two; struct foo three, *four; double five; int *six, seven, eight(); - char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen; + char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen; char *overflow __P((void)); void *mymalloc __P((u_int)); - - /* - * Casts and sizeof's are not followed by a space. NULL is any - * pointer type, and doesn't need to be cast, so use NULL instead - * of (struct foo *)0 or (struct foo *)NULL. Also, test pointers - * against NULL, i.e. use: - * - * (p = f()) == NULL - * not: - * !(p = f()) - * - * Don't use '!' for tests unless it's a boolean, e.g. use - * "if (*p == '\e0')", not "if (!*p)". - * - * Routines returning void * should not have their return values cast - * to any pointer type. - * - * Use err/warn(3), don't roll your own! - */ +.Ed +.Pp +Casts and sizeof's are not followed by a space. NULL is any +pointer type, and doesn't need to be cast, so use NULL instead +of (struct foo *)0 or (struct foo *)NULL. Also, test pointers +against NULL, i.e. use: +.Bd -literal -offset 0i +(p = f()) == NULL +.Ed +.Pp +not: +.Bd -literal -offset 0i +!(p = f()) +.Ed +.Pp +Don't use '!' for tests unless it's a boolean, e.g. use +.Bd -literal -offset 0i +if (*p == '\e0') +.Ed +.Pp +not +.Bd -literal -offset 0i +if (!*p) +.Ed +.Pp +Routines returning void * should not have their return values cast +to any pointer type. +.Pp +Use +.Xr err/warn 3 , +don't roll your own! +.Bd -literal -offset 0i if ((four = malloc(sizeof(struct foo))) == NULL) err(1, NULL); if ((six = (int *)overflow()) == NULL) errx(1, "Number overflowed."); return (eight); } - -/* - * Don't use ANSI function declarations unless you absolutely have too, - * i.e. you're declaring functions with variable numbers of arguments. - * - * ANSI function return values and braces look like regular functions. - */ +.Ed +.Pp +Don't use ANSI function declarations unless you absolutely have too, +i.e. you're declaring functions with variable numbers of arguments. +.Pp +ANSI function return values and braces look like regular functions. +.Bd -literal -offset 0i int function(int a1, int a2) { ... } - -/* Variable numbers of arguments should look like this. */ +.Ed +.Pp +Variable numbers of arguments should look like this. +.Bd -literal -offset 0i #if __STDC__ #include <stdarg.h> #else @@ -314,28 +357,47 @@ vaf(fmt, va_alist) static void usage() -{ /* Insert an empty line if the function has no local variables. */ - - /* - * Use printf(3), not fputs/puts/putchar/whatever, it's faster and - * usually cleaner, not to mention avoiding stupid bugs. - * - * Usage statements should look like the manual pages. Options w/o - * operands come first, in alphabetical order inside a single set of - * braces. Followed by options with operands, in alphabetical order, - * each in braces. Followed by required arguments in the order they - * are specified, followed by optional arguments in the order they - * are specified. A bar ('|') separates either/or options/arguments, - * and multiple options/arguments which are specified together are - * placed in a single set of braces. - * - * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" - * "usage: f [-a | -b] [-c [-de] [-n number]]\en" - */ +{ + /* Insert an empty line if the function has no local variables. */ +.Ed +.Pp +Use +.Xr printf 3 , +not fputs/puts/putchar/whatever, it's faster and usually cleaner, not +to mention avoiding stupid bugs. +.Pp +Usage statements should look like the manual pages. Options w/o +operands come first, in alphabetical order inside a single set of +braces. Followed by options with operands, in alphabetical order, +each in braces. Followed by required arguments in the order they +are specified, followed by optional arguments in the order they +are specified. A bar +.Pq Sq \&| +separates either/or options/arguments, +and multiple options/arguments which are specified together are +placed in a single set of braces. +.Pp +.Bd -ragged -offset 0.3i +"usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" +"usage: f [-a | -b] [-c [-de] [-n number]]\en" +.Ed +.Bd -literal -offset 0i (void)fprintf(stderr, "usage: f [-ab]\en"); exit(1); } .Ed +.Pp +Note that the policy regarding the usage of K&R versus ANSI function +definitions could not be commonly agreed to. While keeping the old +form is more consistent with the existing code base, sticking to it +defeats the migration to the more modern ANSI style. For new code, +chose what you feel is more important. However, when modifying +existing subsystems or files, stick with the style that is already +there. +.Sh SEE ALSO +.Xr err 3 , +.Xr warn 3 , +.Xr sysexits 3 .Sh HISTORY This man page is largely based on the src/admin/style/style file from the BSD 4.4-Lite2 release, with a few updates to reflect the current |