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