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

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>