style revision 1.21
1/* $NetBSD: style,v 1.21 2003/02/23 14:58:50 jhawk Exp $ */ 2 3/* 4 * The revision control tag appears first, with a blank line after it. 5 * Copyright text appears after the revision control tag. 6 */ 7 8/* 9 * The NetBSD source code style guide. 10 * (Previously known as KNF - Kernel Normal Form). 11 * 12 * from: @(#)style 1.12 (Berkeley) 3/18/94 13 */ 14/* 15 * An indent(1) profile approximating the style outlined in 16 * this document lives in /usr/share/misc/indent.pro. It is a 17 * useful tool to assist in converting code to KNF, but indent(1) 18 * output generated using this profile must not be considered to 19 * be an authoritative reference. 20 */ 21 22/* 23 * Source code revision control identifiers appear after any copyright 24 * text. Use the appropriate macros from <sys/cdefs.h>. Usually only one 25 * source file per program contains a __COPYRIGHT() section. 26 * Historic Berkeley code may also have an __SCCSID() section. 27 * Only one instance of each of these macros can occur in each file. 28 */ 29#include <sys/cdefs.h> 30#ifndef __lint 31__COPYRIGHT("@(#) Copyright (c) 2000\n\ 32 The NetBSD Foundation, inc. All rights reserved.\n"); 33__RCSID("$NetBSD: style,v 1.21 2003/02/23 14:58:50 jhawk Exp $"); 34#endif /* !__lint */ 35 36/* 37 * VERY important single-line comments look like this. 38 */ 39 40/* Most single-line comments look like this. */ 41 42/* 43 * Multi-line comments look like this. Make them real sentences. Fill 44 * them so they look like real paragraphs. 45 */ 46 47/* 48 * Attempt to wrap lines longer than 80 characters appropriately. 49 * Refer to the examples below for more information. 50 */ 51 52/* 53 * EXAMPLE HEADER FILE: 54 * 55 * A header file should protect itself against multiple inclusion. 56 * E.g, <sys/socket.h> would contain something like: 57 */ 58#ifndef _SYS_SOCKET_H_ 59#define _SYS_SOCKET_H_ 60/* 61 * Contents of #include file go between the #ifndef and the #endif at the end. 62 */ 63#endif /* !_SYS_SOCKET_H_ */ 64/* 65 * END OF EXAMPLE HEADER FILE. 66 */ 67 68/* 69 * Kernel include files come first. 70 */ 71#include <sys/types.h> /* Non-local includes in brackets. */ 72 73/* 74 * If it's a network program, put the network include files next. 75 * Group the includes files by subdirectory. 76 */ 77#include <net/if.h> 78#include <net/if_dl.h> 79#include <net/route.h> 80#include <netinet/in.h> 81#include <protocols/rwhod.h> 82 83/* 84 * Then there's a blank line, followed by the /usr include files. 85 * The /usr include files should be sorted! 86 */ 87#include <assert.h> 88#include <stdio.h> 89#include <stdlib.h> 90 91/* 92 * Global pathnames are defined in /usr/include/paths.h. Pathnames local 93 * to the program go in pathnames.h in the local directory. 94 */ 95#include <paths.h> 96 97/* Then, there's a blank line, and the user include files. */ 98#include "pathnames.h" /* Local includes in double quotes. */ 99 100/* 101 * ANSI function declarations for private functions (i.e. functions not used 102 * elsewhere) and the main() function go at the top of the source module. 103 * Don't associate a name with the types. I.e. use: 104 * void function(int); 105 * Use your discretion on indenting between the return type and the name, and 106 * how to wrap a prototype too long for a single line. In the latter case, 107 * lining up under the initial left parenthesis may be more readable. 108 * In any case, consistency is important! 109 */ 110static char *function(int, int, float, int); 111static int dirinfo(const char *, struct stat *, struct dirent *, 112 struct statfs *, int *, char **[]); 113static void usage(void); 114int main(int, char *[]); 115 116/* 117 * Macros are capitalized, parenthesized, and should avoid side-effects. 118 * Use one TAB between #define and the macro name; spacing after the macro 119 * name may be any whitespace, as appropriate. 120 * If they are an inline expansion of a function, the function is defined 121 * all in lowercase, the macro has the same name all in uppercase. 122 * If the macro is an expression, wrap the expression in parenthesis. 123 * If the macro is more than a single statement, use ``do { ... } while (0)'', 124 * so that a trailing semicolon works. Right-justify the backslashes; it 125 * makes it easier to read. The CONSTCOND comment is to satisfy lint(1). 126 */ 127#define MACRO(v, w, x, y) \ 128do { \ 129 v = (x) + (y); \ 130 w = (y) + 2; \ 131} while (/* CONSTCOND */ 0) 132 133#define DOUBLE(x) ((x) * 2) 134 135/* Enum types are capitalized. No comma on the last element. */ 136enum enumtype { 137 ONE, 138 TWO 139} et; 140 141/* 142 * When declaring variables in structures, declare them organized by use in 143 * a manner to attempt to minimize memory wastage because of compiler alignment 144 * issues, then by size, and then by alphabetical order. E.g, don't use 145 * ``int a; char *b; int c; char *d''; use ``int a; int b; char *c; char *d''. 146 * Each variable gets its own type and line, although an exception can be made 147 * when declaring bitfields (to clarify that it's part of the one bitfield). 148 * Note that the use of bitfields in general is discouraged. 149 * 150 * Major structures should be declared at the top of the file in which they 151 * are used, or in separate header files, if they are used in multiple 152 * source files. Use of the structures should be by separate declarations 153 * and should be "extern" if they are declared in a header file. 154 * 155 * It may be useful to use a meaningful prefix for each member name. 156 * E.g, for ``struct softc'' the prefix could be ``sc_''. 157 */ 158struct foo { 159 struct foo *next; /* List of active foo */ 160 struct mumble amumble; /* Comment for mumble */ 161 int bar; 162 unsigned int baz:1, /* Bitfield; line up entries if desired */ 163 fuz:5, 164 zap:2; 165 u_int8_t flag; 166}; 167struct foo *foohead; /* Head of global foo list */ 168 169/* Make the structure name match the typedef. */ 170typedef struct BAR { 171 int level; 172} BAR; 173 174/* 175 * All major routines should have a comment briefly describing what 176 * they do. The comment before the "main" routine should describe 177 * what the program does. 178 */ 179int 180main(int argc, char *argv[]) 181{ 182 long num; 183 int ch; 184 char *ep; 185 186 /* 187 * At the start of main(), call setprogname() to set the program 188 * name. This does nothing on NetBSD, but increases portability 189 * to other systems. 190 */ 191 setprogname(argv[0]); 192 193 /* 194 * For consistency, getopt should be used to parse options. Options 195 * should be sorted in the getopt call and the switch statement, unless 196 * parts of the switch cascade. Elements in a switch statement that 197 * cascade should have a FALLTHROUGH comment. Numerical arguments 198 * should be checked for accuracy. Code that cannot be reached should 199 * have a NOTREACHED comment. 200 */ 201 while ((ch = getopt(argc, argv, "abn")) != -1) { 202 switch (ch) { /* Indent the switch. */ 203 case 'a': /* Don't indent the case. */ 204 aflag = 1; 205 /* FALLTHROUGH */ 206 case 'b': 207 bflag = 1; 208 break; 209 case 'n': 210 num = strtol(optarg, &ep, 10); 211 if (num <= 0 || *ep != '\0') 212 errx(1, "illegal number -- %s", optarg); 213 break; 214 case '?': 215 default: 216 usage(); 217 /* NOTREACHED */ 218 } 219 } 220 argc -= optind; 221 argv += optind; 222 223 /* 224 * Space after keywords (while, for, return, switch). No braces are 225 * used for control statements with zero or only a single statement, 226 * unless it's a long statement. 227 * 228 * Forever loops are done with for's, not while's. 229 */ 230 for (p = buf; *p != '\0'; ++p) 231 continue; /* Explicit no-op */ 232 for (;;) 233 stmt; 234 235 /* 236 * Parts of a for loop may be left empty. Don't put declarations 237 * inside blocks unless the routine is unusually complicated. 238 */ 239 for (; cnt < 15; cnt++) { 240 stmt1; 241 stmt2; 242 } 243 244 /* Second level indents are four spaces. */ 245 while (cnt < 20) 246 z = a + really + long + statement + that + needs + two lines + 247 gets + indented + four + spaces + on + the + second + 248 and + subsequent + lines; 249 250 /* 251 * Closing and opening braces go on the same line as the else. 252 * Don't add braces that aren't necessary except in cases where 253 * there are ambiguity or readability issues. 254 */ 255 if (test) { 256 /* 257 * I have a long comment here. 258 */ 259#ifdef zorro 260 z = 1; 261#else 262 b = 3; 263#endif 264 } else if (bar) { 265 stmt; 266 stmt; 267 } else 268 stmt; 269 270 /* No spaces after function names. */ 271 if ((result = function(a1, a2, a3, a4)) == NULL) 272 exit(1); 273 274 /* 275 * Unary operators don't require spaces, binary operators do. 276 * Don't excessively use parenthesis, but they should be used if 277 * statement is really confusing without them, such as: 278 * a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; 279 */ 280 a = ((b->c[0] + ~d == (e || f)) || (g && h)) ? i : (j >> 1); 281 k = !(l & FLAGS); 282 283 /* 284 * Exits should be 0 on success, and 1 on failure. Don't denote 285 * all the possible exit points, using the integers 1 through 300. 286 * Avoid obvious comments such as "Exit 0 on success." 287 */ 288 exit(0); 289} 290 291/* 292 * The function type must be declared on a line by itself 293 * preceding the function. 294 */ 295static char * 296function(int a1, int a2, float fl, int a4) 297{ 298 /* 299 * When declaring variables in functions declare them sorted by size, 300 * then in alphabetical order; multiple ones per line are okay. 301 * Function prototypes should go in the include file "extern.h". 302 * If a line overflows reuse the type keyword. 303 * 304 * DO NOT initialize variables in the declarations. 305 */ 306 extern u_char one; 307 extern char two; 308 struct foo three, *four; 309 double five; 310 int *six, seven; 311 char *eight, *nine, ten, eleven, twelve, thirteen; 312 char fourteen, fifteen, sixteen; 313 314 /* 315 * Casts and sizeof's are not followed by a space. NULL is any 316 * pointer type, and doesn't need to be cast, so use NULL instead 317 * of (struct foo *)0 or (struct foo *)NULL. Also, test pointers 318 * against NULL. I.e. use: 319 * 320 * (p = f()) == NULL 321 * not: 322 * !(p = f()) 323 * 324 * Don't use `!' for tests unless it's a boolean. 325 * E.g. use "if (*p == '\0')", not "if (!*p)". 326 * 327 * Routines returning void * should not have their return values cast 328 * to any pointer type. 329 * 330 * Use err/warn(3), don't roll your own! 331 */ 332 if ((four = malloc(sizeof(struct foo))) == NULL) 333 err(1, NULL); 334 if ((six = (int *)overflow()) == NULL) 335 errx(1, "Number overflowed."); 336 return (eight); 337} 338 339/* 340 * Use ANSI function declarations. ANSI function braces look like 341 * old-style (K&R) function braces. 342 * As per the wrapped prototypes, use your discretion on how to format 343 * the subsequent lines. 344 */ 345static int 346dirinfo(const char *p, struct stat *sb, struct dirent *de, struct statfs *sf, 347 int *rargc, char **rargv[]) 348{ /* Insert an empty line if the function has no local variables. */ 349 350 /* 351 * In system libraries, catch obviously invalid function arguments 352 * using _DIAGASSERT(3). 353 */ 354 _DIAGASSERT(p != NULL); 355 _DIAGASSERT(filedesc != -1); 356 357 if (stat(p, sb) < 0) 358 err(1, "Unable to stat %s", p); 359 360 /* 361 * To printf 64 bit quantities, use %ll and cast to (long long). 362 */ 363 printf("The size of %s is %lld\n", p, (long long)sb->st_size); 364} 365 366/* 367 * Functions that support variable numbers of arguments should look like this. 368 * (With the #include <stdarg.h> appearing at the top of the file with the 369 * other include files). 370 */ 371#include <stdarg.h> 372 373void 374vaf(const char *fmt, ...) 375{ 376 va_list ap; 377 378 va_start(ap, fmt); 379 STUFF; 380 va_end(ap); 381 /* No return needed for void functions. */ 382} 383 384static void 385usage(void) 386{ 387 388 /* 389 * Use printf(3), not fputs/puts/putchar/whatever, it's faster and 390 * usually cleaner, not to mention avoiding stupid bugs. 391 * Use snprintf(3) or strlcpy(3)/strlcat(3) instead of sprintf(3); 392 * again to avoid stupid bugs. 393 * 394 * Usage statements should look like the manual pages. Options w/o 395 * operands come first, in alphabetical order inside a single set of 396 * braces. Followed by options with operands, in alphabetical order, 397 * each in braces. Followed by required arguments in the order they 398 * are specified, followed by optional arguments in the order they 399 * are specified. A bar (`|') separates either/or options/arguments, 400 * and multiple options/arguments which are specified together are 401 * placed in a single set of braces. 402 * 403 * Use getprogname() instead of hardcoding the program name. 404 * 405 * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n" 406 * "usage: f [-a | -b] [-c [-de] [-n number]]\n" 407 */ 408 (void)fprintf(stderr, "usage: %s [-ab]\n", getprogname()); 409 exit(1); 410} 411