From b030a30523649cec609e2281b1b8aad0b7419f6a Mon Sep 17 00:00:00 2001 From: Poul-Henning Kamp Date: Thu, 14 Dec 1995 10:50:27 +0000 Subject: [PATCH] Add a slightly edited version of the style document. --- share/man/man9/Makefile | 2 +- share/man/man9/intro.9 | 10 +- share/man/man9/style.9 | 351 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 355 insertions(+), 8 deletions(-) create mode 100644 share/man/man9/style.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 972a9a0606bd..e92ee6720a4d 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,5 +1,5 @@ # @(#)Makefile 8.1 (Berkeley) 6/5/93 -MAN8= intro.9 +MAN8= intro.9 style.9 .include diff --git a/share/man/man9/intro.9 b/share/man/man9/intro.9 index 02e42dc5b5a0..a9be6e6e1578 100644 --- a/share/man/man9/intro.9 +++ b/share/man/man9/intro.9 @@ -66,13 +66,9 @@ violate it blatantly. We don't mind it too badly if you have your own style, but please make sure we can read it too. -In particular there are some iron-clad requirements: -.Bl -enum -compact -.It -TAB stops is 8. -.It -All funtion names start in col 1. -.El +Please take time to read +.Xr style 9 +for more information. .Sh NAMING THINGS Some general rules exist: diff --git a/share/man/man9/style.9 b/share/man/man9/style.9 new file mode 100644 index 000000000000..b9820bd5c24f --- /dev/null +++ b/share/man/man9/style.9 @@ -0,0 +1,351 @@ +.Dd December 14, 1995 +.Dt STYLE 9 +.Os FreeBSD 2.2 +.Sh NAME +.Nm STYLE +.Nd "Kernel source file style guide" +.Sh DESCRIPTION +This file contains an example of the preferred style for kernel source +files in the FreeBSD source tree. + +.Bd -literal +/* + * Style guide for the 4BSD KNF (Kernel Normal Form). + * + * @(#)style 1.14 (Berkeley) 4/28/95 + */ + +/* + * VERY important single-line comments look like this. + */ + +/* Most single-line comments look like this. */ + +/* + * 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 + * OR , but not both! + * includes , and it's okay to depend on that. + */ +#include /* Non-local includes in brackets. */ + +/* If it's a network program, put the network include files next. */ +#include +#include +#include +#include +#include + +/* + * Then there's a blank line, followed by the /usr include files. + * The /usr include files should be sorted! + */ +#include + +/* + * Global pathnames are defined in /usr/include/paths.h. Pathnames + * local to the program go in pathnames.h in the local directory. + */ +#include + +/* Then, there's a blank line, and the user include files. */ +#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. + */ +#define MACRO(x, y) { \e + variable = (x) + (y); \e + (y) += 2; \e +} + +/* Enum types are capitalized. */ +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. + */ +struct foo { + struct foo *next; /* List of active foo */ + struct mumble amumble; /* Comment for mumble */ + int bar; +}; +struct foo *foohead; /* Head of global foo list */ + +/* Make the structure name match the typedef. */ +typedef struct _bar { + int level; +} BAR; + +/* + * 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 if the + * source file in general is compilable with an 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)); + +/* + * All major routines should have a comment briefly describing what + * they do. The comment before the "main" routine should describe + * what the program does. + */ +int +main(argc, argv) + int argc; + char *argv[]; +{ + extern char *optarg; + extern int optind; + long num; + 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. + */ + while ((ch = getopt(argc, argv, "abn")) != EOF) + switch (ch) { /* Indent the switch. */ + case 'a': /* Don't indent the case. */ + aflag = 1; + /* FALLTHROUGH */ + case 'b': + bflag = 1; + break; + case 'n': + num = strtol(optarg, &ep, 10); + if (num <= 0 || *ep != '\e0') + err("illegal number -- %s", optarg); + break; + case '?': + default: + usage(); + /* NOTREACHED */ + } + 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. + */ + 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. + */ + for (; cnt < 15; cnt++) { + stmt1; + stmt2; + } + + /* Second level indents are four spaces. */ + 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. + */ + if (test) + stmt; + else if (bar) { + stmt; + stmt; + } else + stmt; + + /* No spaces after function names. */ + 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. + */ + 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." */ +} + +/* + * If a function type is declared, it should be on a line + * by itself preceeding the function. + */ +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. + */ + 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; + 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! + */ + 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. + */ +int +function(int a1, int a2) +{ + ... +} + +/* Variable numbers of arguments should look like this. */ +#if __STDC__ +#include +#else +#include +#endif + +void +#if __STDC__ +vaf(const char *fmt, ...) +#else +vaf(fmt, va_alist) + char *fmt; + va_dcl +#endif +{ + va_list ap; +#if __STDC__ + va_start(ap, fmt); +#else + va_start(ap); +#endif + STUFF; + + va_end(ap); /* No return needed for void functions. */ +} + +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" + */ + (void)fprintf(stderr, "usage: f [-ab]\en"); + exit(1); +} +.Ed +.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 +practice and desire of the FreeBSD project. + +