1/* 2 * Style guide for the 4BSD KNF (Kernel Normal Form). 3 * 4 * from: @(#)style 1.12 (Berkeley) 3/18/94 5 * $Id: style,v 1.3 1994/12/19 14:14:40 cgd Exp $ 6 */ 7 8/* 9 * VERY important single-line comments look like this. 10 */ 11 12/* Most single-line comments look like this. */ 13 14/* 15 * Multi-line comments look like this. Make them real sentences. Fill 16 * them so they look like real paragraphs. 17 */ 18 19/* 20 * Kernel include files come first; normally, you'll need <sys/types.h> 21 * OR <sys/param.h>, but not both! <sys/types.h> includes <sys/cdefs.h>, 22 * and it's okay to depend on that. 23 */ 24#include <sys/types.h> /* Non-local includes in brackets. */ 25 26/* If it's a network program, put the network include files next. */ 27#include <net/if.h> 28#include <net/if_dl.h> 29#include <net/route.h> 30#include <netinet/in.h> 31#include <protocols/rwhod.h> 32 33/* 34 * Then there's a blank line, followed by the /usr include files. 35 * The /usr include files should be sorted! 36 */ 37#include <stdio.h> 38 39/* 40 * Global pathnames are defined in /usr/include/paths.h. Pathnames local 41 * to the program go in pathnames.h in the local directory. 42 */ 43#include <paths.h> 44 45/* Then, there's a blank line, and the user include files. */ 46#include "pathnames.h" /* Local includes in double quotes. */ 47 48/* 49 * ANSI function declarations for private functions (i.e. functions not used 50 * elsewhere) go at the top of the source module. Use the __P macro from 51 * the include file <sys/cdefs.h>. Only the kernel has a name associated with 52 * the types, i.e. in the kernel use: 53 * 54 * void function __P((int a)); 55 * 56 * in user land use: 57 * 58 * void function __P((int)); 59 */ 60static char *function __P((int, const char *)); 61static void usage __P((void)); 62 63/* 64 * Macros are capitalized, parenthesized, and should avoid side-effects. 65 * If they are an inline expansion of a function, the function is defined 66 * all in lowercase, the macro has the same name all in uppercase. If the 67 * macro needs more than a single line, use braces. Right-justify the 68 * backslashes, it makes it easier to read. 69 */ 70#define MACRO(x, y) { \ 71 variable = (x) + (y); \ 72 (y) += 2; \ 73} 74 75/* Enum types are capitalized. */ 76enum enumtype { ONE, TWO } et; 77 78/* 79 * When declaring variables in structures, declare them sorted by use, then 80 * by size, and then by alphabetical order. The first category normally 81 * doesn't apply, but there are exceptions. Each one gets its own line. 82 * Put a tab after the first word, i.e. use "int^Ix;" and "struct^Ifoo *x;". 83 * 84 * Major structures should be declared at the top of the file in which they 85 * are used, or in separate header files, if they are used in multiple 86 * source files. Use of the structures should be by separate declarations 87 * and should be "extern" if they are declared in a header file. 88 */ 89struct foo { 90 struct foo *next; /* List of active foo */ 91 struct mumble amumble; /* Comment for mumble */ 92 int bar; 93}; 94struct foo *foohead; /* Head of global foo list */ 95 96/* Make the structure name match the typedef. */ 97typedef struct _bar { 98 int level; 99} BAR; 100 101/* 102 * All major routines should have a comment briefly describing what 103 * they do. The comment before the "main" routine should describe 104 * what the program does. 105 */ 106int 107main(argc, argv) 108 int argc; 109 char *argv[]; 110{ 111 extern char *optarg; 112 extern int optind; 113 long num; 114 int ch; 115 char *ep; 116 117 /* 118 * For consistency, getopt should be used to parse options. Options 119 * should be sorted in the getopt call and the switch statement, unless 120 * parts of the switch cascade. Elements in a switch statement that 121 * cascade should have a FALLTHROUGH comment. Numerical arguments 122 * should be checked for accuracy. Code that cannot be reached should 123 * have a NOTREACHED comment. 124 */ 125 while ((ch = getopt(argc, argv, "abn")) != EOF) 126 switch (ch) { /* Indent the switch. */ 127 case 'a': /* Don't indent the case. */ 128 aflag = 1; 129 /* FALLTHROUGH */ 130 case 'b': 131 bflag = 1; 132 break; 133 case 'n': 134 num = strtol(optarg, &ep, 10); 135 if (num <= 0 || *ep != '\0') 136 err("illegal number -- %s", optarg); 137 break; 138 case '?': 139 default: 140 usage(); 141 /* NOTREACHED */ 142 } 143 argc -= optind; 144 argv += optind; 145 146 /* 147 * Space after keywords (while, for, return, switch). No braces are 148 * used for control statements with zero or only a single statement. 149 * 150 * Forever loops are done with for's, not while's. 151 */ 152 for (p = buf; *p != '\0'; ++p); 153 for (;;) 154 stmt; 155 156 /* 157 * Parts of a for loop may be left empty. Don't put declarations 158 * inside blocks unless the routine is unusually complicated. 159 */ 160 for (; cnt < 15; cnt++) { 161 stmt1; 162 stmt2; 163 } 164 165 /* Second level indents are four spaces. */ 166 while (cnt < 20) 167 z = a + really + long + statment + that + needs + two lines + 168 gets + indented + four + spaces + on + the + second + 169 and + subsequent + lines. 170 171 /* 172 * Closing and opening braces go on the same line as the else. 173 * Don't add braces that aren't necessary. 174 */ 175 if (test) 176 stmt; 177 else if (bar) { 178 stmt; 179 stmt; 180 } else 181 stmt; 182 183 /* No spaces after function names. */ 184 if (error = function(a1, a2)) 185 exit(error); 186 187 /* 188 * Unary operators don't require spaces, binary operators do. Don't 189 * use parenthesis unless they're required for precedence, or the 190 * statement is really confusing without them. 191 */ 192 a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; 193 k = !(l & FLAGS); 194 195 /* 196 * Exits should be 0 on success, and 1 on failure. Don't denote 197 * all the possible exit points, using the integers 1 through 300. 198 */ 199 exit(0); /* Avoid obvious comments such as "Exit 0 on success." */ 200} 201 202/* 203 * If a function type is declared, it should be on a line 204 * by itself preceeding the function. 205 */ 206static char * 207function(a1, a2, fl, a4) 208 int a1, a2, a4; /* Declare ints, too, don't default them. */ 209 float fl; /* List in order declared, as much as possible. */ 210{ 211 /* 212 * When declaring variables in functions declare them sorted by size, 213 * then in alphabetical order; multiple ones per line are okay. Old 214 * style function declarations can go on the same line. ANSI style 215 * function declarations should go in the include file "extern.h". 216 * If a line overflows reuse the type keyword. 217 * 218 * DO NOT initialize variables in the declarations. 219 */ 220 extern u_char one; 221 extern char two; 222 struct foo three, *four; 223 double five; 224 int *six, seven, eight(); 225 char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen; 226 char *overflow __P((void)); 227 void *mymalloc __P((u_int)); 228 229 /* 230 * Casts and sizeof's are not followed by a space. NULL is any 231 * pointer type, and doesn't need to be cast, so use NULL instead 232 * of (struct foo *)0 or (struct foo *)NULL. Also, test pointers 233 * against NULL, i.e. use: 234 * 235 * (p = f()) == NULL 236 * not: 237 * !(p = f()) 238 * 239 * Don't use '!' for tests unless it's a boolean, e.g. use 240 * "if (*p == '\0')", not "if (!*p)". 241 * 242 * Routines returning void * should not have their return values cast 243 * to any pointer type. 244 * 245 * Use err/warn(3), don't roll your own! 246 */ 247 if ((four = malloc(sizeof(struct foo))) == NULL) 248 err(1, NULL); 249 if ((six = (int *)overflow()) == NULL) 250 errx(1, "Number overflowed."); 251 return (eight); 252} 253 254/* 255 * Don't use ANSI function declarations unless you absolutely have too, 256 * i.e. you're declaring functions with variable numbers of arguments. 257 * 258 * ANSI function braces look like regular function braces. 259 */ 260function(int a1, int a2) 261{ 262 ... 263} 264 265/* Variable numbers of arguments should look like this. */ 266#if __STDC__ 267#include <stdarg.h> 268#else 269#include <varargs.h> 270#endif 271 272void 273#if __STDC__ 274vaf(const char *fmt, ...) 275#else 276vaf(fmt, va_alist) 277 char *fmt; 278 va_dcl 279#endif 280{ 281 va_list ap; 282#if __STDC__ 283 va_start(ap, fmt); 284#else 285 va_start(ap); 286#endif 287 STUFF; 288 289 va_end(ap); /* No return needed for void functions. */ 290} 291 292static void 293usage() 294{ /* Insert an empty line if the function has no local variables. */ 295 296 /* 297 * Use printf(3), not fputs/puts/putchar/whatever, it's faster and 298 * usually cleaner, not to mention avoiding stupid bugs. 299 * 300 * Usage statements should look like the manual pages. Options w/o 301 * operands come first, in alphabetical order inside a single set of 302 * braces. Followed by options with operands, in alphabetical order, 303 * each in braces. Followed by required arguments in the order they 304 * are specified, followed by optional arguments in the order they 305 * are specified. A bar ('|') separates either/or options/arguments, 306 * and multiple options/arguments which are specified together are 307 * placed in a single set of braces. 308 * 309 * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n" 310 * "usage: f [-a | -b] [-c [-de] [-n number]]\n" 311 */ 312 (void)fprintf(stderr, "usage: f [-ab]\n"); 313 exit(1); 314} 315