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