style.9 revision 17196
1.Dd December 14, 1995 2.Dt STYLE 9 3.Os FreeBSD 2.2 4.Sh NAME 5.Nm style 6.Nd "Kernel source file style guide" 7.Sh DESCRIPTION 8This file contains an example of the preferred style for kernel source 9files in the FreeBSD source tree. 10.Bd -literal -offset 0i 11/* 12 * Style guide for the 4BSD KNF (Kernel Normal Form). 13 * 14 * @(#)style 1.14 (Berkeley) 4/28/95 15 * 16 * $Id: style.9,v 1.8 1996/06/13 19:52:42 wollman Exp $ 17 * 18 */ 19 20/* 21 * VERY important single-line comments look like this. 22 */ 23 24/* Most single-line comments look like this. */ 25 26/* 27 * Multi-line comments look like this. Make them real sentences. Fill 28 * them so they look like real paragraphs. 29 */ 30.Ed 31.Pp 32Kernel include files come first; normally, you'll need <sys/types.h> 33OR <sys/param.h>, but not both! <sys/types.h> includes <sys/cdefs.h>, 34and it's okay to depend on that. 35.Bd -literal -offset 0i 36#include <sys/types.h> /* Non-local includes in brackets. */ 37.Ed 38.Pp 39If it's a network program, put the network include files next. 40.Bd -literal -offset 0i 41#include <net/if.h> 42#include <net/if_dl.h> 43#include <net/route.h> 44#include <netinet/in.h> 45#include <protocols/rwhod.h> 46.Ed 47.Pp 48Then there's a blank line, followed by the /usr include files. 49The /usr include files should be sorted! 50.Bd -literal -offset 0i 51#include <stdio.h> 52.Ed 53.Pp 54Global pathnames are defined in /usr/include/paths.h. Pathnames local 55to the program go in pathnames.h in the local directory. 56.Bd -literal -offset 0i 57#include <paths.h> 58.Ed 59.Pp 60Then, there's a blank line, and the user include files. 61.Bd -literal -offset 0i 62#include "pathnames.h" /* Local includes in double quotes. */ 63.Ed 64.Pp 65Macros are capitalized, parenthesized, and should avoid side-effects. 66If they are an inline expansion of a function, the function is defined 67all in lowercase, the macro has the same name all in uppercase. If the 68macro needs more than a single line, use braces. Right-justify the 69backslashes, it makes it easier to read. 70.Bd -literal -offset 0i 71#define MACRO(x, y) { \e 72 variable = (x) + (y); \e 73 (y) += 2; \e 74} 75.Ed 76.Pp 77Enum types are capitalized. 78.Bd -literal -offset 0i 79enum enumtype { ONE, TWO } et; 80.Ed 81.Pp 82When declaring variables in structures, declare them sorted by use, then 83by size, and then by alphabetical order. The first category normally 84doesn't apply, but there are exceptions. Each one gets its own line. 85Put a tab after the first word, i.e. use 86.Ql int^Ix; 87and 88.Ql struct^Ifoo *x; . 89.Pp 90Major structures should be declared at the top of the file in which they 91are used, or in separate header files, if they are used in multiple 92source files. Use of the structures should be by separate declarations 93and should be "extern" if they are declared in a header file. 94.Bd -literal -offset 0i 95struct foo { 96 struct foo *next; /* List of active foo */ 97 struct mumble amumble; /* Comment for mumble */ 98 int bar; 99}; 100struct foo *foohead; /* Head of global foo list */ 101 102/* Make the structure name match the typedef. */ 103typedef struct _bar { 104 int level; 105} BAR; 106.Ed 107.Pp 108All functions are prototyped somewhere. 109.Pp 110Function prototypes for private functions (i.e. functions not used 111elsewhere) go at the top of the first source module. Functions 112local to one source module should be declared 113.Ql static . 114.Pp 115Functions used from other parts of the kernel are prototyped in the 116relevant include file. 117.Pp 118Functions that are used locally in more than one module go into a 119separate header file, e.g. 120.Pa extern.h . 121.Pp 122Only use the __P macro from the include file <sys/cdefs.h> if the source 123file in general is (to be) compilable with a K&R Old testament compiler. 124.Pp 125Only the kernel has a name associated with the types, i.e. in the kernel 126use: 127.Bd -literal -offset 0i 128void function __P((int fd)); 129.Ed 130.Pp 131in user land use: 132.Bd -literal -offset 0i 133 void function __P((int)); 134 135static char *function __P((int, const char *)); 136static void usage __P((void)); 137 138/* 139 * All major routines should have a comment briefly describing what 140 * they do. The comment before the "main" routine should describe 141 * what the program does. 142 */ 143int 144main(argc, argv) 145 int argc; 146 char *argv[]; 147{ 148 extern char *optarg; 149 extern int optind; 150 long num; 151 int ch; 152 char *ep; 153 154.Ed 155.Pp 156For consistency, getopt should be used to parse options. Options 157should be sorted in the getopt call and the switch statement, unless 158parts of the switch cascade. Elements in a switch statement that 159cascade should have a FALLTHROUGH comment. Numerical arguments 160should be checked for accuracy. Code that cannot be reached should 161have a NOTREACHED comment. 162.Bd -literal -offset 0i 163 while ((ch = getopt(argc, argv, "abn")) != EOF) 164 switch (ch) { /* Indent the switch. */ 165 case 'a': /* Don't indent the case. */ 166 aflag = 1; 167 /* FALLTHROUGH */ 168 case 'b': 169 bflag = 1; 170 break; 171 case 'n': 172 num = strtol(optarg, &ep, 10); 173 if (num <= 0 || *ep != '\e0') 174 err("illegal number -- %s", optarg); 175 break; 176 case '?': 177 default: 178 usage(); 179 /* NOTREACHED */ 180 } 181 argc -= optind; 182 argv += optind; 183 184.Ed 185.Pp 186Space after keywords (while, for, return, switch). No braces are 187used for control statements with zero or only a single statement. 188.Pp 189Forever loops are done with for's, not while's. 190.Bd -literal -offset 0i 191 for (p = buf; *p != '\e0'; ++p); 192 for (;;) 193 stmt; 194 195.Ed 196.Pp 197Parts of a for loop may be left empty. Don't put declarations 198inside blocks unless the routine is unusually complicated. 199.Bd -literal -offset 0i 200 for (; cnt < 15; cnt++) { 201 stmt1; 202 stmt2; 203 } 204.Ed 205.Pp 206Second level indents are four spaces. 207.Bd -literal -offset 0i 208 while (cnt < 20) 209 z = a + really + long + statement + that + needs + 210 two lines + gets + indented + four + spaces + 211 on + the + second + and + subsequent + lines. 212.Ed 213.Pp 214Closing and opening braces go on the same line as the else. 215Don't add braces that aren't necessary. 216.Bd -literal -offset 0i 217 if (test) 218 stmt; 219 else if (bar) { 220 stmt; 221 stmt; 222 } else 223 stmt; 224.Ed 225.Pp 226No spaces after function names. 227.Bd -literal -offset 0i 228 if (error = function(a1, a2)) 229 exit(error); 230.Ed 231.Pp 232Unary operators don't require spaces, binary operators do. Don't 233use parenthesis unless they're required for precedence, or the 234statement is really confusing without them. 235.Bd -literal -offset 0i 236 a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; 237 k = !(l & FLAGS); 238.Ed 239.Pp 240Exits should be 0 on success, or according to the predefined 241values in 242.Xr sysexits 3 . 243.Bd -literal -offset 0i 244 exit(EX_OK); /* 245 * Avoid obvious comments such as 246 * "Exit 0 on success." 247 */ 248} 249.Ed 250.Pp 251The function type should be on a line by itself 252preceding the function. 253.Bd -literal -offset 0i 254static char * 255function(a1, a2, fl, a4) 256 int a1, a2, a4; /* Declare ints, too, don't default them. */ 257 float fl; /* List in order declared, as much as possible. */ 258{ 259.Ed 260.Pp 261When declaring variables in functions declare them sorted by size, 262then in alphabetical order; multiple ones per line are okay. 263Declaring functions inside functions is not recommendable, since their 264linkage scope is always global. If a line overflows reuse the type 265keyword. 266.Pp 267Be careful to not obfuscate the code by initializing variables in 268the declarations. Use this feature only thoughtfully. 269.Bd -literal -offset 0i 270 extern u_char one; 271 extern char two; 272 struct foo three, *four; 273 double five; 274 int *six, seven, eight(); 275 char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen; 276 char *overflow __P((void)); 277 void *mymalloc __P((u_int)); 278.Ed 279.Pp 280Casts and sizeof's are not followed by a space. 281.Pp 282NULL is the preferred null pointer constant. Use NULL instead of 283(type *)0 or (type *)NULL in contexts where the compiler knows the 284type, e.g., in assignments. Use (type *)NULL in other contexts, 285in particular for all function args. (Casting is essential for 286varadic args and is necessary for other args if the function prototype 287might not be in scope; since we pretend to support K&R compilers, 288most prototypes might not be in scope.) 289Test pointers 290against NULL, e.g., use: 291.Bd -literal -offset 0i 292(p = f()) == NULL 293.Ed 294.Pp 295not: 296.Bd -literal -offset 0i 297!(p = f()) 298.Ed 299.Pp 300Don't use '!' for tests unless it's a boolean, e.g. use 301.Bd -literal -offset 0i 302if (*p == '\e0') 303.Ed 304.Pp 305not 306.Bd -literal -offset 0i 307if (!*p) 308.Ed 309.Pp 310Routines returning void * should not have their return values cast 311to any pointer type. 312.Pp 313Use 314.Xr err 3 315or 316.Xr warn 3 , 317don't roll your own! 318.Bd -literal -offset 0i 319 if ((four = malloc(sizeof(struct foo))) == NULL) 320 err(1, (char *)NULL); 321 if ((six = (int *)overflow()) == NULL) 322 errx(1, "Number overflowed."); 323 return (eight); 324} 325.Ed 326.Pp 327Don't use ANSI function declarations unless you absolutely have too, 328i.e. you're declaring functions with variable numbers of arguments. 329.Pp 330ANSI function return values and braces look like regular functions. 331.Bd -literal -offset 0i 332int 333function(int a1, int a2) 334{ 335 ... 336} 337.Ed 338.Pp 339Variable numbers of arguments should look like this. 340.Bd -literal -offset 0i 341#if __STDC__ 342#include <stdarg.h> 343#else 344#include <varargs.h> 345#endif 346 347void 348#if __STDC__ 349vaf(const char *fmt, ...) 350#else 351vaf(fmt, va_alist) 352 char *fmt; 353 va_dcl 354#endif 355{ 356 va_list ap; 357#if __STDC__ 358 va_start(ap, fmt); 359#else 360 va_start(ap); 361#endif 362 STUFF; 363 364 va_end(ap); /* No return needed for void functions. */ 365} 366 367static void 368usage() 369{ 370 /* Insert an empty line if the function has no local variables. */ 371.Ed 372.Pp 373Use 374.Xr printf 3 , 375not fputs/puts/putchar/whatever, it's faster and usually cleaner, not 376to mention avoiding stupid bugs. 377.Pp 378Usage statements should look like the manual pages. Options w/o 379operands come first, in alphabetical order inside a single set of 380braces. Followed by options with operands, in alphabetical order, 381each in braces. Followed by required arguments in the order they 382are specified, followed by optional arguments in the order they 383are specified. A bar 384.Pq Sq \&| 385separates either/or options/arguments, 386and multiple options/arguments which are specified together are 387placed in a single set of braces. 388.Pp 389.Bd -ragged -offset 0.3i 390"usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" 391"usage: f [-a | -b] [-c [-de] [-n number]]\en" 392.Ed 393.Bd -literal -offset 0i 394 (void)fprintf(stderr, "usage: f [-ab]\en"); 395 exit(1); 396} 397.Ed 398.Pp 399Note that the policy regarding the usage of K&R versus ANSI function 400definitions could not be commonly agreed to. While keeping the old 401form is more consistent with the existing code base, sticking to it 402defeats the migration to the more modern ANSI style. For new code, 403chose what you feel is more important. However, when modifying 404existing subsystems or files, stick with the style that is already 405there. 406.Sh SEE ALSO 407.Xr err 3 , 408.Xr warn 3 , 409.Xr sysexits 3 410.Sh HISTORY 411This man page is largely based on the src/admin/style/style file from 412the BSD 4.4-Lite2 release, with a few updates to reflect the current 413practice and desire of the FreeBSD project. 414 415 416