Annotation of src/share/misc/style, Revision 1.35
1.35 ! rillig 1: /* $NetBSD: style,v 1.34 2005/08/20 09:03:29 rillig 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.
28: */
29: #include <sys/cdefs.h>
30: __COPYRIGHT("@(#) Copyright (c) 2000\n\
31: The NetBSD Foundation, inc. All rights reserved.\n");
1.35 ! rillig 32: __RCSID("$NetBSD: style,v 1.34 2005/08/20 09:03:29 rillig Exp $");
1.12 lukem 33:
34: /*
1.1 cgd 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:
1.2 cgd 45: /*
1.12 lukem 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.
1.2 cgd 68: */
69: #include <sys/types.h> /* Non-local includes in brackets. */
70:
1.12 lukem 71: /*
72: * If it's a network program, put the network include files next.
73: * Group the includes files by subdirectory.
74: */
1.2 cgd 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: */
1.20 kleink 85: #include <assert.h>
1.25 lukem 86: #include <errno.h>
1.2 cgd 87: #include <stdio.h>
1.18 cgd 88: #include <stdlib.h>
1.1 cgd 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: */
1.2 cgd 94: #include <paths.h>
95:
96: /* Then, there's a blank line, and the user include files. */
1.12 lukem 97: #include "pathnames.h" /* Local includes in double quotes. */
1.1 cgd 98:
99: /*
1.2 cgd 100: * ANSI function declarations for private functions (i.e. functions not used
1.12 lukem 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,
1.15 lukem 106: * lining up under the initial left parenthesis may be more readable.
1.12 lukem 107: * In any case, consistency is important!
108: */
109: static char *function(int, int, float, int);
110: static int dirinfo(const char *, struct stat *, struct dirent *,
111: struct statfs *, int *, char **[]);
112: static void usage(void);
113: int main(int, char *[]);
1.1 cgd 114:
115: /*
116: * Macros are capitalized, parenthesized, and should avoid side-effects.
1.22 jhawk 117: * Spacing before and after the macro name may be any whitespace, though
118: * use of TABs should be consistent through a file.
1.1 cgd 119: * If they are an inline expansion of a function, the function is defined
1.12 lukem 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
1.13 lukem 124: * makes it easier to read. The CONSTCOND comment is to satisfy lint(1).
1.12 lukem 125: */
126: #define MACRO(v, w, x, y) \
127: do { \
128: v = (x) + (y); \
129: w = (y) + 2; \
130: } while (/* CONSTCOND */ 0)
131:
1.15 lukem 132: #define DOUBLE(x) ((x) * 2)
1.12 lukem 133:
134: /* Enum types are capitalized. No comma on the last element. */
135: enum enumtype {
136: ONE,
137: TWO
138: } et;
139:
140: /*
1.16 enami 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
1.12 lukem 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.
1.1 cgd 148: *
1.2 cgd 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
1.1 cgd 152: * and should be "extern" if they are declared in a header file.
1.12 lukem 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_''.
1.1 cgd 156: */
157: struct foo {
1.12 lukem 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;
1.27 simonb 164: uint8_t flag;
1.1 cgd 165: };
166: struct foo *foohead; /* Head of global foo list */
1.2 cgd 167:
168: /* Make the structure name match the typedef. */
1.12 lukem 169: typedef struct BAR {
170: int level;
1.2 cgd 171: } BAR;
1.12 lukem 172:
1.32 junyoung 173: /* C99 uintN_t is preferred over u_intN_t. */
174: uint32_t zero;
175:
1.1 cgd 176: /*
177: * All major routines should have a comment briefly describing what
1.2 cgd 178: * they do. The comment before the "main" routine should describe
1.1 cgd 179: * what the program does.
180: */
1.2 cgd 181: int
1.12 lukem 182: main(int argc, char *argv[])
1.1 cgd 183: {
184: long num;
185: int ch;
186: char *ep;
187:
188: /*
1.17 cgd 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: /*
1.2 cgd 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.
1.1 cgd 202: */
1.12 lukem 203: while ((ch = getopt(argc, argv, "abn")) != -1) {
1.1 cgd 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':
1.25 lukem 212: errno = 0;
1.1 cgd 213: num = strtol(optarg, &ep, 10);
1.25 lukem 214: if (num <= 0 || *ep != '\0' || (errno == ERANGE &&
215: (num == LONG_MAX || num == LONG_MIN)) )
1.12 lukem 216: errx(1, "illegal number -- %s", optarg);
1.1 cgd 217: break;
218: case '?':
219: default:
220: usage();
1.2 cgd 221: /* NOTREACHED */
1.1 cgd 222: }
1.12 lukem 223: }
1.1 cgd 224: argc -= optind;
225: argv += optind;
226:
227: /*
228: * Space after keywords (while, for, return, switch). No braces are
1.12 lukem 229: * used for control statements with zero or only a single statement,
230: * unless it's a long statement.
1.1 cgd 231: *
232: * Forever loops are done with for's, not while's.
233: */
1.12 lukem 234: for (p = buf; *p != '\0'; ++p)
235: continue; /* Explicit no-op */
1.1 cgd 236: for (;;)
237: stmt;
1.12 lukem 238:
1.1 cgd 239: /*
1.2 cgd 240: * Parts of a for loop may be left empty. Don't put declarations
241: * inside blocks unless the routine is unusually complicated.
1.1 cgd 242: */
243: for (; cnt < 15; cnt++) {
244: stmt1;
245: stmt2;
246: }
247:
1.2 cgd 248: /* Second level indents are four spaces. */
249: while (cnt < 20)
1.16 enami 250: z = a + really + long + statement + that + needs + two lines +
1.1 cgd 251: gets + indented + four + spaces + on + the + second +
1.7 enami 252: and + subsequent + lines;
1.1 cgd 253:
254: /*
1.2 cgd 255: * Closing and opening braces go on the same line as the else.
1.12 lukem 256: * Don't add braces that aren't necessary except in cases where
257: * there are ambiguity or readability issues.
1.1 cgd 258: */
1.12 lukem 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) {
1.1 cgd 269: stmt;
270: stmt;
271: } else
272: stmt;
1.12 lukem 273:
1.2 cgd 274: /* No spaces after function names. */
1.12 lukem 275: if ((result = function(a1, a2, a3, a4)) == NULL)
276: exit(1);
1.1 cgd 277:
278: /*
1.12 lukem 279: * Unary operators don't require spaces, binary operators do.
280: * Don't excessively use parenthesis, but they should be used if
1.9 lukem 281: * statement is really confusing without them, such as:
282: * a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
1.1 cgd 283: */
1.9 lukem 284: a = ((b->c[0] + ~d == (e || f)) || (g && h)) ? i : (j >> 1);
1.2 cgd 285: k = !(l & FLAGS);
1.1 cgd 286:
287: /*
1.26 jmmv 288: * Exits should be EXIT_SUCCESS on success, and EXIT_FAILURE on
289: * failure. Don't denote all the possible exit points, using the
1.29 christos 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.
1.1 cgd 293: */
1.29 christos 294: return EXIT_SUCCESS;
1.1 cgd 295: }
296:
297: /*
1.8 simonb 298: * The function type must be declared on a line by itself
1.16 enami 299: * preceding the function.
1.1 cgd 300: */
301: static char *
1.12 lukem 302: function(int a1, int a2, float fl, int a4)
1.1 cgd 303: {
304: /*
305: * When declaring variables in functions declare them sorted by size,
1.12 lukem 306: * then in alphabetical order; multiple ones per line are okay.
307: * Function prototypes should go in the include file "extern.h".
1.1 cgd 308: * If a line overflows reuse the type keyword.
309: *
1.2 cgd 310: * DO NOT initialize variables in the declarations.
1.1 cgd 311: */
312: extern u_char one;
313: extern char two;
314: struct foo three, *four;
315: double five;
1.12 lukem 316: int *six, seven;
317: char *eight, *nine, ten, eleven, twelve, thirteen;
318: char fourteen, fifteen, sixteen;
1.1 cgd 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
1.12 lukem 324: * against NULL. I.e. use:
1.1 cgd 325: *
1.12 lukem 326: * (p = f()) == NULL
1.1 cgd 327: * not:
328: * !(p = f())
1.2 cgd 329: *
1.12 lukem 330: * Don't use `!' for tests unless it's a boolean.
331: * E.g. use "if (*p == '\0')", not "if (!*p)".
332: *
1.31 christos 333: * Routines returning ``void *'' should not have their return
334: * values cast to more specific pointer types.
1.2 cgd 335: *
336: * Use err/warn(3), don't roll your own!
1.1 cgd 337: */
338: if ((four = malloc(sizeof(struct foo))) == NULL)
1.2 cgd 339: err(1, NULL);
1.1 cgd 340: if ((six = (int *)overflow()) == NULL)
1.2 cgd 341: errx(1, "Number overflowed.");
1.23 fvdl 342:
343: /* No parentheses are needed around the return value. */
344: return eight;
1.1 cgd 345: }
346:
1.2 cgd 347: /*
1.12 lukem 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: */
353: static int
354: dirinfo(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. */
1.19 kleink 357:
358: /*
359: * In system libraries, catch obviously invalid function arguments
360: * using _DIAGASSERT(3).
361: */
362: _DIAGASSERT(p != NULL);
363: _DIAGASSERT(filedesc != -1);
1.12 lukem 364:
1.14 lukem 365: if (stat(p, sb) < 0)
366: err(1, "Unable to stat %s", p);
367:
368: /*
1.34 rillig 369: * To printf 64 bit quantities, use %lld and cast to (long long)
370: * or use %llu and cast to (unsigned long long).
1.14 lukem 371: */
1.35 ! rillig 372: (void)printf("The size of %s is %lld\n", p, (long long)sb->st_size);
1.2 cgd 373: }
374:
1.12 lukem 375: /*
376: * Functions that support variable numbers of arguments should look like this.
377: * (With the #include <stdarg.h> appearing at the top of the file with the
378: * other include files).
379: */
1.2 cgd 380: #include <stdarg.h>
381:
382: void
383: vaf(const char *fmt, ...)
384: {
385: va_list ap;
1.12 lukem 386:
1.2 cgd 387: va_start(ap, fmt);
388: STUFF;
1.12 lukem 389: va_end(ap);
390: /* No return needed for void functions. */
1.1 cgd 391: }
392:
393: static void
1.12 lukem 394: usage(void)
395: {
1.1 cgd 396:
397: /*
398: * Use printf(3), not fputs/puts/putchar/whatever, it's faster and
399: * usually cleaner, not to mention avoiding stupid bugs.
1.12 lukem 400: * Use snprintf(3) or strlcpy(3)/strlcat(3) instead of sprintf(3);
401: * again to avoid stupid bugs.
1.1 cgd 402: *
403: * Usage statements should look like the manual pages. Options w/o
404: * operands come first, in alphabetical order inside a single set of
405: * braces. Followed by options with operands, in alphabetical order,
406: * each in braces. Followed by required arguments in the order they
407: * are specified, followed by optional arguments in the order they
1.12 lukem 408: * are specified. A bar (`|') separates either/or options/arguments,
1.1 cgd 409: * and multiple options/arguments which are specified together are
410: * placed in a single set of braces.
411: *
1.17 cgd 412: * Use getprogname() instead of hardcoding the program name.
1.12 lukem 413: *
1.1 cgd 414: * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n"
415: * "usage: f [-a | -b] [-c [-de] [-n number]]\n"
416: */
1.17 cgd 417: (void)fprintf(stderr, "usage: %s [-ab]\n", getprogname());
1.33 rillig 418: exit(EXIT_FAILURE);
1.1 cgd 419: }
CVSweb <webmaster@jp.NetBSD.org>