style.9 revision 17196
1234287Sdim.Dd December 14, 1995 2234287Sdim.Dt STYLE 9 3353358Sdim.Os FreeBSD 2.2 4353358Sdim.Sh NAME 5353358Sdim.Nm style 6234287Sdim.Nd "Kernel source file style guide" 7234287Sdim.Sh DESCRIPTION 8234287SdimThis file contains an example of the preferred style for kernel source 9234287Sdimfiles in the FreeBSD source tree. 10234287Sdim.Bd -literal -offset 0i 11234287Sdim/* 12234287Sdim * Style guide for the 4BSD KNF (Kernel Normal Form). 13234287Sdim * 14234287Sdim * @(#)style 1.14 (Berkeley) 4/28/95 15234287Sdim * 16234287Sdim * $Id: style.9,v 1.8 1996/06/13 19:52:42 wollman Exp $ 17234287Sdim * 18234287Sdim */ 19234287Sdim 20234287Sdim/* 21249423Sdim * VERY important single-line comments look like this. 22234287Sdim */ 23234287Sdim 24234287Sdim/* Most single-line comments look like this. */ 25234287Sdim 26234287Sdim/* 27234287Sdim * Multi-line comments look like this. Make them real sentences. Fill 28234287Sdim * them so they look like real paragraphs. 29234287Sdim */ 30234287Sdim.Ed 31234287Sdim.Pp 32234287SdimKernel include files come first; normally, you'll need <sys/types.h> 33249423SdimOR <sys/param.h>, but not both! <sys/types.h> includes <sys/cdefs.h>, 34249423Sdimand it's okay to depend on that. 35341825Sdim.Bd -literal -offset 0i 36234287Sdim#include <sys/types.h> /* Non-local includes in brackets. */ 37341825Sdim.Ed 38234287Sdim.Pp 39249423SdimIf it's a network program, put the network include files next. 40249423Sdim.Bd -literal -offset 0i 41234287Sdim#include <net/if.h> 42234287Sdim#include <net/if_dl.h> 43234287Sdim#include <net/route.h> 44234287Sdim#include <netinet/in.h> 45234287Sdim#include <protocols/rwhod.h> 46234287Sdim.Ed 47234287Sdim.Pp 48276479SdimThen there's a blank line, followed by the /usr include files. 49276479SdimThe /usr include files should be sorted! 50276479Sdim.Bd -literal -offset 0i 51276479Sdim#include <stdio.h> 52341825Sdim.Ed 53341825Sdim.Pp 54234287SdimGlobal pathnames are defined in /usr/include/paths.h. Pathnames local 55276479Sdimto the program go in pathnames.h in the local directory. 56234287Sdim.Bd -literal -offset 0i 57234287Sdim#include <paths.h> 58341825Sdim.Ed 59234287Sdim.Pp 60234287SdimThen, there's a blank line, and the user include files. 61234287Sdim.Bd -literal -offset 0i 62234287Sdim#include "pathnames.h" /* Local includes in double quotes. */ 63234287Sdim.Ed 64360784Sdim.Pp 65280031SdimMacros are capitalized, parenthesized, and should avoid side-effects. 66234287SdimIf they are an inline expansion of a function, the function is defined 67234287Sdimall in lowercase, the macro has the same name all in uppercase. If the 68341825Sdimmacro needs more than a single line, use braces. Right-justify the 69341825Sdimbackslashes, it makes it easier to read. 70341825Sdim.Bd -literal -offset 0i 71341825Sdim#define MACRO(x, y) { \e 72341825Sdim variable = (x) + (y); \e 73341825Sdim (y) += 2; \e 74341825Sdim} 75341825Sdim.Ed 76341825Sdim.Pp 77341825SdimEnum types are capitalized. 78341825Sdim.Bd -literal -offset 0i 79234287Sdimenum enumtype { ONE, TWO } et; 80234287Sdim.Ed 81341825Sdim.Pp 82234287SdimWhen declaring variables in structures, declare them sorted by use, then 83234287Sdimby size, and then by alphabetical order. The first category normally 84234287Sdimdoesn't apply, but there are exceptions. Each one gets its own line. 85276479SdimPut a tab after the first word, i.e. use 86234287Sdim.Ql int^Ix; 87234287Sdimand 88234287Sdim.Ql struct^Ifoo *x; . 89341825Sdim.Pp 90234287SdimMajor structures should be declared at the top of the file in which they 91234287Sdimare used, or in separate header files, if they are used in multiple 92234287Sdimsource files. Use of the structures should be by separate declarations 93234287Sdimand should be "extern" if they are declared in a header file. 94249423Sdim.Bd -literal -offset 0i 95249423Sdimstruct foo { 96234287Sdim struct foo *next; /* List of active foo */ 97234287Sdim struct mumble amumble; /* Comment for mumble */ 98234287Sdim int bar; 99234287Sdim}; 100234287Sdimstruct foo *foohead; /* Head of global foo list */ 101234287Sdim 102280031Sdim/* Make the structure name match the typedef. */ 103360784Sdimtypedef struct _bar { 104280031Sdim int level; 105280031Sdim} BAR; 106280031Sdim.Ed 107234287Sdim.Pp 108234287SdimAll functions are prototyped somewhere. 109234287Sdim.Pp 110234287SdimFunction prototypes for private functions (i.e. functions not used 111341825Sdimelsewhere) go at the top of the first source module. Functions 112234287Sdimlocal to one source module should be declared 113234287Sdim.Ql static . 114234287Sdim.Pp 115234287SdimFunctions used from other parts of the kernel are prototyped in the 116234287Sdimrelevant include file. 117234287Sdim.Pp 118234287SdimFunctions that are used locally in more than one module go into a 119234287Sdimseparate header file, e.g. 120234287Sdim.Pa extern.h . 121341825Sdim.Pp 122234287SdimOnly use the __P macro from the include file <sys/cdefs.h> if the source 123234287Sdimfile in general is (to be) compilable with a K&R Old testament compiler. 124234287Sdim.Pp 125234287SdimOnly the kernel has a name associated with the types, i.e. in the kernel 126234287Sdimuse: 127341825Sdim.Bd -literal -offset 0i 128234287Sdimvoid function __P((int fd)); 129341825Sdim.Ed 130234287Sdim.Pp 131234287Sdimin user land use: 132234287Sdim.Bd -literal -offset 0i 133234287Sdim void function __P((int)); 134234287Sdim 135234287Sdimstatic char *function __P((int, const char *)); 136234287Sdimstatic void usage __P((void)); 137234287Sdim 138234287Sdim/* 139234287Sdim * All major routines should have a comment briefly describing what 140234287Sdim * 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