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