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