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