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

Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.

Diff for /src/share/misc/style between version 1.8 and 1.31

version 1.8, 1998/09/01 06:51:09 version 1.31, 2005/02/03 00:27:55
Line 1 
Line 1 
 /*      $NetBSD$        */  /* $NetBSD$ */
   
 /*  /*
  * Style guide for the 4BSD KNF (Kernel Normal Form).   * The revision control tag appears first, with a blank line after it.
    * Copyright text appears after the revision control tag.
    */
   
   /*
    * The NetBSD source code style guide.
    * (Previously known as KNF - Kernel Normal Form).
  *   *
  *      from: @(#)style 1.12 (Berkeley) 3/18/94   *      from: @(#)style 1.12 (Berkeley) 3/18/94
  */   */
   /*
    * An indent(1) profile approximating the style outlined in
    * this document lives in /usr/share/misc/indent.pro.  It is a
    * useful tool to assist in converting code to KNF, but indent(1)
    * output generated using this profile must not be considered to
    * be an authoritative reference.
    */
   
   /*
    * Source code revision control identifiers appear after any copyright
    * text.  Use the appropriate macros from <sys/cdefs.h>.  Usually only one
    * source file per program contains a __COPYRIGHT() section.
    * Historic Berkeley code may also have an __SCCSID() section.
    * Only one instance of each of these macros can occur in each file.
    */
   #include <sys/cdefs.h>
   __COPYRIGHT("@(#) Copyright (c) 2000\n\
           The NetBSD Foundation, inc. All rights reserved.\n");
   __RCSID("$NetBSD$");
   
 /*  /*
  * VERY important single-line comments look like this.   * VERY important single-line comments look like this.
Line 18 
Line 43 
  */   */
   
 /*  /*
  * Kernel include files come first; normally, you'll need <sys/types.h>   * Attempt to wrap lines longer than 80 characters appropriately.
  * OR <sys/param.h>, but not both!  <sys/types.h> includes <sys/cdefs.h>,   * Refer to the examples below for more information.
  * and it's okay to depend on that.   */
   
   /*
    * EXAMPLE HEADER FILE:
    *
    * A header file should protect itself against multiple inclusion.
    * E.g, <sys/socket.h> would contain something like:
    */
   #ifndef _SYS_SOCKET_H_
   #define _SYS_SOCKET_H_
   /*
    * Contents of #include file go between the #ifndef and the #endif at the end.
    */
   #endif /* !_SYS_SOCKET_H_ */
   /*
    * END OF EXAMPLE HEADER FILE.
    */
   
   /*
    * Kernel include files come first.
  */   */
 #include <sys/types.h>          /* Non-local includes in brackets. */  #include <sys/types.h>          /* Non-local includes in brackets. */
   
 /* If it's a network program, put the network include files next. */  /*
    * If it's a network program, put the network include files next.
    * Group the includes files by subdirectory.
    */
 #include <net/if.h>  #include <net/if.h>
 #include <net/if_dl.h>  #include <net/if_dl.h>
 #include <net/route.h>  #include <net/route.h>
Line 35 
Line 82 
  * Then there's a blank line, followed by the /usr include files.   * Then there's a blank line, followed by the /usr include files.
  * The /usr include files should be sorted!   * The /usr include files should be sorted!
  */   */
   #include <assert.h>
   #include <errno.h>
 #include <stdio.h>  #include <stdio.h>
   #include <stdlib.h>
   
 /*  /*
  * Global pathnames are defined in /usr/include/paths.h.  Pathnames local   * Global pathnames are defined in /usr/include/paths.h.  Pathnames local
Line 44 
Line 94 
 #include <paths.h>  #include <paths.h>
   
 /* Then, there's a blank line, and the user include files. */  /* Then, there's a blank line, and the user include files. */
 #include "pathnames.h"          /* Local includes in double quotes. */  #include "pathnames.h"          /* Local includes in double quotes. */
   
 /*  /*
  * ANSI function declarations for private functions (i.e. functions not used   * ANSI function declarations for private functions (i.e. functions not used
  * elsewhere) go at the top of the source module.  Use the __P macro from   * elsewhere) and the main() function go at the top of the source module.
  * the include file <sys/cdefs.h>.  Only the kernel has a name associated with   * Don't associate a name with the types.  I.e. use:
  * the types, i.e. in the kernel use:   *      void function(int);
  *   * Use your discretion on indenting between the return type and the name, and
  *      void function __P((int a));   * how to wrap a prototype too long for a single line.  In the latter case,
  *   * lining up under the initial left parenthesis may be more readable.
  * in user land use:   * In any case, consistency is important!
  *   */
  *      void function __P((int));  static char *function(int, int, float, int);
  */  static int dirinfo(const char *, struct stat *, struct dirent *,
 static char     *function __P((int, const char *));                     struct statfs *, int *, char **[]);
 static void      usage __P((void));  static void usage(void);
   int main(int, char *[]);
   
 /*  /*
  * Macros are capitalized, parenthesized, and should avoid side-effects.   * Macros are capitalized, parenthesized, and should avoid side-effects.
    * Spacing before and after the macro name may be any whitespace, though
    * use of TABs should be consistent through a file.
  * If they are an inline expansion of a function, the function is defined   * If they are an inline expansion of a function, the function is defined
  * all in lowercase, the macro has the same name all in uppercase. If the   * all in lowercase, the macro has the same name all in uppercase.
  * macro needs more than a single line, use braces.  Right-justify the   * If the macro is an expression, wrap the expression in parenthesis.
  * backslashes, it makes it easier to read.   * If the macro is more than a single statement, use ``do { ... } while (0)'',
  */   * so that a trailing semicolon works.  Right-justify the backslashes; it
 #define MACRO(x, y) {                                                   \   * makes it easier to read. The CONSTCOND comment is to satisfy lint(1).
         variable = (x) + (y);                                           \   */
         (y) += 2;                                                       \  #define MACRO(v, w, x, y)                                               \
 }  do {                                                                    \
           v = (x) + (y);                                                  \
 /* Enum types are capitalized. */          w = (y) + 2;                                                    \
 enum enumtype { ONE, TWO } et;  } while (/* CONSTCOND */ 0)
   
 /*  #define DOUBLE(x) ((x) * 2)
  * When declaring variables in structures, declare them sorted by use, then  
  * by size, and then by alphabetical order.  The first category normally  /* Enum types are capitalized.  No comma on the last element. */
  * doesn't apply, but there are exceptions.  Each one gets its own line.  enum enumtype {
  * Put a tab after the first word, i.e. use "int^Ix;" and "struct^Ifoo *x;".          ONE,
           TWO
   } et;
   
   /*
    * When declaring variables in structures, declare them organized by use in
    * a manner to attempt to minimize memory wastage because of compiler alignment
    * issues, then by size, and then by alphabetical order. E.g, don't use
    * ``int a; char *b; int c; char *d''; use ``int a; int b; char *c; char *d''.
    * Each variable gets its own type and line, although an exception can be made
    * when declaring bitfields (to clarify that it's part of the one bitfield).
    * Note that the use of bitfields in general is discouraged.
  *   *
  * Major structures should be declared at the top of the file in which they   * Major structures should be declared at the top of the file in which they
  * are used, or in separate header files, if they are used in multiple   * are used, or in separate header files, if they are used in multiple
  * source files.  Use of the structures should be by separate declarations   * source files.  Use of the structures should be by separate declarations
  * and should be "extern" if they are declared in a header file.   * and should be "extern" if they are declared in a header file.
    *
    * It may be useful to use a meaningful prefix for each member name.
    * E.g, for ``struct softc'' the prefix could be ``sc_''.
  */   */
 struct foo {  struct foo {
         struct  foo *next;      /* List of active foo */          struct foo *next;       /* List of active foo */
         struct  mumble amumble; /* Comment for mumble */          struct mumble amumble;  /* Comment for mumble */
         int     bar;          int bar;
           unsigned int baz:1,     /* Bitfield; line up entries if desired */
                        fuz:5,
                        zap:2;
           uint8_t flag;
 };  };
 struct foo *foohead;            /* Head of global foo list */  struct foo *foohead;            /* Head of global foo list */
   
 /* Make the structure name match the typedef. */  /* Make the structure name match the typedef. */
 typedef struct _bar {  typedef struct BAR {
         int     level;          int level;
 } BAR;  } BAR;
   
 /*  /*
  * All major routines should have a comment briefly describing what   * All major routines should have a comment briefly describing what
  * they do.  The comment before the "main" routine should describe   * they do.  The comment before the "main" routine should describe
  * what the program does.   * what the program does.
  */   */
 int  int
 main(argc, argv)  main(int argc, char *argv[])
         int argc;  
         char *argv[];  
 {  {
         extern char *optarg;  
         extern int optind;  
         long num;          long num;
         int ch;          int ch;
         char *ep;          char *ep;
   
         /*          /*
            * At the start of main(), call setprogname() to set the program
            * name.  This does nothing on NetBSD, but increases portability
            * to other systems.
            */
           setprogname(argv[0]);
   
           /*
          * For consistency, getopt should be used to parse options.  Options           * For consistency, getopt should be used to parse options.  Options
          * should be sorted in the getopt call and the switch statement, unless           * should be sorted in the getopt call and the switch statement, unless
          * parts of the switch cascade.  Elements in a switch statement that           * parts of the switch cascade.  Elements in a switch statement that
Line 123  main(argc, argv)
Line 197  main(argc, argv)
          * should be checked for accuracy.  Code that cannot be reached should           * should be checked for accuracy.  Code that cannot be reached should
          * have a NOTREACHED comment.           * have a NOTREACHED comment.
          */           */
         while ((ch = getopt(argc, argv, "abn")) != -1)          while ((ch = getopt(argc, argv, "abn")) != -1) {
                 switch (ch) {           /* Indent the switch. */                  switch (ch) {           /* Indent the switch. */
                 case 'a':               /* Don't indent the case. */                  case 'a':               /* Don't indent the case. */
                         aflag = 1;                          aflag = 1;
Line 132  main(argc, argv)
Line 206  main(argc, argv)
                         bflag = 1;                          bflag = 1;
                         break;                          break;
                 case 'n':                  case 'n':
                           errno = 0;
                         num = strtol(optarg, &ep, 10);                          num = strtol(optarg, &ep, 10);
                         if (num <= 0 || *ep != '\0')                          if (num <= 0 || *ep != '\0' || (errno == ERANGE &&
                                 err("illegal number -- %s", optarg);                              (num == LONG_MAX || num == LONG_MIN)) )
                                   errx(1, "illegal number -- %s", optarg);
                         break;                          break;
                 case '?':                  case '?':
                 default:                  default:
                         usage();                          usage();
                         /* NOTREACHED */                          /* NOTREACHED */
                 }                  }
           }
         argc -= optind;          argc -= optind;
         argv += optind;          argv += optind;
   
         /*          /*
          * Space after keywords (while, for, return, switch).  No braces are           * Space after keywords (while, for, return, switch).  No braces are
          * used for control statements with zero or only a single statement.           * used for control statements with zero or only a single statement,
            * unless it's a long statement.
          *           *
          * Forever loops are done with for's, not while's.           * Forever loops are done with for's, not while's.
          */           */
         for (p = buf; *p != '\0'; ++p);          for (p = buf; *p != '\0'; ++p)
                   continue;               /* Explicit no-op */
         for (;;)          for (;;)
                 stmt;                  stmt;
   
         /*          /*
          * Parts of a for loop may be left empty.  Don't put declarations           * Parts of a for loop may be left empty.  Don't put declarations
          * inside blocks unless the routine is unusually complicated.           * inside blocks unless the routine is unusually complicated.
Line 165  main(argc, argv)
Line 244  main(argc, argv)
   
         /* Second level indents are four spaces. */          /* Second level indents are four spaces. */
         while (cnt < 20)          while (cnt < 20)
                 z = a + really + long + statment + that + needs + two lines +                  z = a + really + long + statement + that + needs + two lines +
                     gets + indented + four + spaces + on + the + second +                      gets + indented + four + spaces + on + the + second +
                     and + subsequent + lines;                      and + subsequent + lines;
   
         /*          /*
          * Closing and opening braces go on the same line as the else.           * Closing and opening braces go on the same line as the else.
          * Don't add braces that aren't necessary.           * Don't add braces that aren't necessary except in cases where
            * there are ambiguity or readability issues.
          */           */
         if (test)          if (test) {
                 stmt;                  /*
         else if (bar) {                   * I have a long comment here.
                    */
   #ifdef zorro
                   z = 1;
   #else
                   b = 3;
   #endif
           } else if (bar) {
                 stmt;                  stmt;
                 stmt;                  stmt;
         } else          } else
                 stmt;                  stmt;
   
         /* No spaces after function names. */          /* No spaces after function names. */
         if (error = function(a1, a2))          if ((result = function(a1, a2, a3, a4)) == NULL)
                 exit(error);                  exit(1);
   
         /*          /*
          * Unary operators don't require spaces, binary operators do. Don't           * Unary operators don't require spaces, binary operators do.
          * use parenthesis unless they're required for precedence, or the           * Don't excessively use parenthesis, but they should be used if
          * statement is really confusing without them.           * statement is really confusing without them, such as:
            * a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
          */           */
         a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;          a = ((b->c[0] + ~d == (e || f)) || (g && h)) ? i : (j >> 1);
         k = !(l & FLAGS);          k = !(l & FLAGS);
   
         /*          /*
          * Exits should be 0 on success, and 1 on failure.  Don't denote           * Exits should be EXIT_SUCCESS on success, and EXIT_FAILURE on
          * all the possible exit points, using the integers 1 through 300.           * failure.  Don't denote all the possible exit points, using the
            * integers 1 through 127.  Avoid obvious comments such as "Exit
            * 0 on success.". Since main is a function that returns an int,
            * prefer returning from it, than calling exit.
          */           */
         exit(0);    /* Avoid obvious comments such as "Exit 0 on success." */          return EXIT_SUCCESS;
 }  }
   
 /*  /*
  * The function type must be declared on a line by itself   * The function type must be declared on a line by itself
  * preceeding the function.   * preceding the function.
  */   */
 static char *  static char *
 function(a1, a2, fl, a4)  function(int a1, int a2, float fl, int a4)
         int a1, a2, a4; /* Declare ints, too, don't default them. */  
         float fl;       /* List in order declared, as much as possible. */  
 {  {
         /*          /*
          * When declaring variables in functions declare them sorted by size,           * When declaring variables in functions declare them sorted by size,
          * then in alphabetical order; multiple ones per line are okay.  Old           * then in alphabetical order; multiple ones per line are okay.
          * style function declarations can go on the same line.  ANSI style           * Function prototypes should go in the include file "extern.h".
          * function declarations should go in the include file "extern.h".  
          * If a line overflows reuse the type keyword.           * If a line overflows reuse the type keyword.
          *           *
          * DO NOT initialize variables in the declarations.           * DO NOT initialize variables in the declarations.
          */           */
           extern uint32_t zero;
         extern u_char one;          extern u_char one;
         extern char two;          extern char two;
         struct foo three, *four;          struct foo three, *four;
         double five;          double five;
         int *six, seven, eight();          int *six, seven;
         char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen;          char *eight, *nine, ten, eleven, twelve, thirteen;
         char *overflow __P((void));          char fourteen, fifteen, sixteen;
         void *mymalloc __P((u_int));  
   
         /*          /*
          * Casts and sizeof's are not followed by a space.  NULL is any           * Casts and sizeof's are not followed by a space.  NULL is any
          * pointer type, and doesn't need to be cast, so use NULL instead           * pointer type, and doesn't need to be cast, so use NULL instead
          * of (struct foo *)0 or (struct foo *)NULL.  Also, test pointers           * of (struct foo *)0 or (struct foo *)NULL.  Also, test pointers
          * against NULL, i.e. use:           * against NULL.  I.e. use:
          *           *
          *      (p = f()) == NULL           *      (p = f()) == NULL
          * not:           * not:
          *      !(p = f())           *      !(p = f())
          *           *
          * Don't use '!' for tests unless it's a boolean, e.g. use           * Don't use `!' for tests unless it's a boolean.
          * "if (*p == '\0')", not "if (!*p)".           * E.g. use "if (*p == '\0')", not "if (!*p)".
          *           *
          * Routines returning void * should not have their return values cast           * Routines returning ``void *'' should not have their return
          * to any pointer type.           * values cast to more specific pointer types.
          *           *
          * Use err/warn(3), don't roll your own!           * Use err/warn(3), don't roll your own!
          */           */
Line 249  function(a1, a2, fl, a4)
Line 337  function(a1, a2, fl, a4)
                 err(1, NULL);                  err(1, NULL);
         if ((six = (int *)overflow()) == NULL)          if ((six = (int *)overflow()) == NULL)
                 errx(1, "Number overflowed.");                  errx(1, "Number overflowed.");
         return (eight);  
           /* No parentheses are needed around the return value. */
           return eight;
 }  }
   
 /*  /*
  * Don't use ANSI function declarations unless you absolutely have to,   * Use ANSI function declarations.  ANSI function braces look like
  * i.e. you're declaring functions with variable numbers of arguments.   * old-style (K&R) function braces.
  *   * As per the wrapped prototypes, use your discretion on how to format
  * ANSI function braces look like regular function braces.   * the subsequent lines.
  */   */
 function(int a1, int a2)  static int
 {  dirinfo(const char *p, struct stat *sb, struct dirent *de, struct statfs *sf,
         ...          int *rargc, char **rargv[])
   {       /* Insert an empty line if the function has no local variables. */
   
           /*
            * In system libraries, catch obviously invalid function arguments
            * using _DIAGASSERT(3).
            */
           _DIAGASSERT(p != NULL);
           _DIAGASSERT(filedesc != -1);
   
           if (stat(p, sb) < 0)
                   err(1, "Unable to stat %s", p);
   
           /*
            * To printf 64 bit quantities, use %ll and cast to (long long).
            */
           (void)printf("The size of %s is %lld\n", p, (long long)sb->st_size);
 }  }
   
 /* Variable numbers of arguments should look like this. */  /*
 #if __STDC__   * Functions that support variable numbers of arguments should look like this.
    * (With the #include <stdarg.h> appearing at the top of the file with the
    * other include files).
    */
 #include <stdarg.h>  #include <stdarg.h>
 #else  
 #include <varargs.h>  
 #endif  
   
 void  void
 #if __STDC__  
 vaf(const char *fmt, ...)  vaf(const char *fmt, ...)
 #else  
 vaf(fmt, va_alist)  
         char *fmt;  
         va_dcl  
 #endif  
 {  {
         va_list ap;          va_list ap;
 #if __STDC__  
         va_start(ap, fmt);          va_start(ap, fmt);
 #else  
         va_start(ap);  
 #endif  
         STUFF;          STUFF;
           va_end(ap);
         va_end(ap);             /* No return needed for void functions. */                                  /* No return needed for void functions. */
 }  }
   
 static void  static void
 usage()  usage(void)
 {       /* Insert an empty line if the function has no local variables. */  {
   
         /*          /*
          * Use printf(3), not fputs/puts/putchar/whatever, it's faster and           * Use printf(3), not fputs/puts/putchar/whatever, it's faster and
          * usually cleaner, not to mention avoiding stupid bugs.           * usually cleaner, not to mention avoiding stupid bugs.
            * Use snprintf(3) or strlcpy(3)/strlcat(3) instead of sprintf(3);
            * again to avoid stupid bugs.
          *           *
          * Usage statements should look like the manual pages.  Options w/o           * Usage statements should look like the manual pages.  Options w/o
          * operands come first, in alphabetical order inside a single set of           * operands come first, in alphabetical order inside a single set of
          * braces.  Followed by options with operands, in alphabetical order,           * braces.  Followed by options with operands, in alphabetical order,
          * each in braces.  Followed by required arguments in the order they           * each in braces.  Followed by required arguments in the order they
          * are specified, followed by optional arguments in the order they           * are specified, followed by optional arguments in the order they
          * are specified.  A bar ('|') separates either/or options/arguments,           * are specified.  A bar (`|') separates either/or options/arguments,
          * and multiple options/arguments which are specified together are           * and multiple options/arguments which are specified together are
          * placed in a single set of braces.           * placed in a single set of braces.
          *           *
            * Use getprogname() instead of hardcoding the program name.
            *
          * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n"           * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n"
          * "usage: f [-a | -b] [-c [-de] [-n number]]\n"           * "usage: f [-a | -b] [-c [-de] [-n number]]\n"
          */           */
         (void)fprintf(stderr, "usage: f [-ab]\n");          (void)fprintf(stderr, "usage: %s [-ab]\n", getprogname());
         exit(1);          exit(1);
 }  }

Legend:
Removed from v.1.8  
changed lines
  Added in v.1.31

CVSweb <webmaster@jp.NetBSD.org>