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