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