[BACK]Return to style CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / share / misc

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>