home *** CD-ROM | disk | FTP | other *** search
/ H4CK3R 4 / hacker04 / 04_HACK04.ISO / darwin / darwinx86.iso / usr / share / misc / style < prev    next >
Encoding:
Text File  |  2001-09-17  |  8.6 KB  |  316 lines
  1. /*    $NetBSD: style,v 1.7 1998/02/09 06:58:39 enami Exp $    */
  2.  
  3. /*
  4.  * Style guide for the 4BSD KNF (Kernel Normal Form).
  5.  *
  6.  *    from: @(#)style    1.12 (Berkeley) 3/18/94
  7.  */
  8.  
  9. /*
  10.  * VERY important single-line comments look like this.
  11.  */
  12.  
  13. /* Most single-line comments look like this. */
  14.  
  15. /*
  16.  * Multi-line comments look like this.  Make them real sentences.  Fill
  17.  * them so they look like real paragraphs.
  18.  */
  19.  
  20. /*
  21.  * Kernel include files come first; normally, you'll need <sys/types.h>
  22.  * OR <sys/param.h>, but not both!  <sys/types.h> includes <sys/cdefs.h>,
  23.  * and it's okay to depend on that.
  24.  */
  25. #include <sys/types.h>        /* Non-local includes in brackets. */
  26.  
  27. /* If it's a network program, put the network include files next. */
  28. #include <net/if.h>
  29. #include <net/if_dl.h>
  30. #include <net/route.h>
  31. #include <netinet/in.h>
  32. #include <protocols/rwhod.h>
  33.  
  34. /*
  35.  * Then there's a blank line, followed by the /usr include files.
  36.  * The /usr include files should be sorted!
  37.  */
  38. #include <stdio.h>
  39.  
  40. /*
  41.  * Global pathnames are defined in /usr/include/paths.h.  Pathnames local
  42.  * to the program go in pathnames.h in the local directory.
  43.  */
  44. #include <paths.h>
  45.  
  46. /* Then, there's a blank line, and the user include files. */
  47. #include "pathnames.h"        /* Local includes in double quotes. */        
  48.  
  49. /*
  50.  * ANSI function declarations for private functions (i.e. functions not used
  51.  * elsewhere) go at the top of the source module.  Use the __P macro from
  52.  * the include file <sys/cdefs.h>.  Only the kernel has a name associated with
  53.  * the types, i.e. in the kernel use:
  54.  *
  55.  *    void function __P((int a));
  56.  *
  57.  * in user land use:
  58.  *
  59.  *    void function __P((int));
  60.  */
  61. static char    *function __P((int, const char *));
  62. static void     usage __P((void));
  63.  
  64. /*
  65.  * Macros are capitalized, parenthesized, and should avoid side-effects.
  66.  * If they are an inline expansion of a function, the function is defined
  67.  * all in lowercase, the macro has the same name all in uppercase. If the
  68.  * macro needs more than a single line, use braces.  Right-justify the
  69.  * backslashes, it makes it easier to read.
  70.  */
  71. #define    MACRO(x, y) {                            \
  72.     variable = (x) + (y);                        \
  73.     (y) += 2;                            \
  74. }
  75.  
  76. /* Enum types are capitalized. */
  77. enum enumtype { ONE, TWO } et;
  78.  
  79. /*
  80.  * When declaring variables in structures, declare them sorted by use, then
  81.  * by size, and then by alphabetical order.  The first category normally
  82.  * doesn't apply, but there are exceptions.  Each one gets its own line.
  83.  * Put a tab after the first word, i.e. use "int^Ix;" and "struct^Ifoo *x;".
  84.  *
  85.  * Major structures should be declared at the top of the file in which they
  86.  * are used, or in separate header files, if they are used in multiple
  87.  * source files.  Use of the structures should be by separate declarations
  88.  * and should be "extern" if they are declared in a header file.
  89.  */
  90. struct foo {
  91.     struct    foo *next;    /* List of active foo */
  92.     struct    mumble amumble;    /* Comment for mumble */
  93.     int    bar;
  94. };
  95. struct foo *foohead;        /* Head of global foo list */
  96.  
  97. /* Make the structure name match the typedef. */
  98. typedef struct _bar {
  99.     int    level;
  100. } BAR;
  101.     
  102. /*
  103.  * All major routines should have a comment briefly describing what
  104.  * they do.  The comment before the "main" routine should describe
  105.  * what the program does.
  106.  */
  107. int
  108. main(argc, argv)
  109.     int argc;
  110.     char *argv[];
  111. {
  112.     extern char *optarg;
  113.     extern int optind;
  114.     long num;
  115.     int ch;
  116.     char *ep;
  117.  
  118.     /*
  119.      * For consistency, getopt should be used to parse options.  Options
  120.      * should be sorted in the getopt call and the switch statement, unless
  121.      * parts of the switch cascade.  Elements in a switch statement that
  122.      * cascade should have a FALLTHROUGH comment.  Numerical arguments
  123.      * should be checked for accuracy.  Code that cannot be reached should
  124.      * have a NOTREACHED comment.
  125.      */
  126.     while ((ch = getopt(argc, argv, "abn")) != -1)
  127.         switch (ch) {        /* Indent the switch. */
  128.         case 'a':        /* Don't indent the case. */
  129.             aflag = 1;
  130.             /* FALLTHROUGH */
  131.         case 'b':
  132.             bflag = 1;
  133.             break;
  134.         case 'n':
  135.             num = strtol(optarg, &ep, 10);
  136.                         if (num <= 0 || *ep != '\0')
  137.                                 err("illegal number -- %s", optarg);
  138.             break;
  139.         case '?':
  140.         default:
  141.             usage();
  142.             /* NOTREACHED */
  143.         }
  144.     argc -= optind;
  145.     argv += optind;
  146.  
  147.     /*
  148.      * Space after keywords (while, for, return, switch).  No braces are
  149.      * used for control statements with zero or only a single statement.
  150.      *
  151.      * Forever loops are done with for's, not while's.
  152.      */
  153.     for (p = buf; *p != '\0'; ++p);
  154.     for (;;)
  155.         stmt;
  156.     
  157.     /*
  158.      * Parts of a for loop may be left empty.  Don't put declarations
  159.      * inside blocks unless the routine is unusually complicated.
  160.      */
  161.     for (; cnt < 15; cnt++) {
  162.         stmt1;
  163.         stmt2;
  164.     }
  165.  
  166.     /* Second level indents are four spaces. */
  167.     while (cnt < 20)
  168.         z = a + really + long + statment + that + needs + two lines +
  169.             gets + indented + four + spaces + on + the + second +
  170.             and + subsequent + lines;
  171.  
  172.     /*
  173.      * Closing and opening braces go on the same line as the else.
  174.      * Don't add braces that aren't necessary.
  175.      */
  176.     if (test)
  177.         stmt;
  178.     else if (bar) {
  179.         stmt;
  180.         stmt;
  181.     } else
  182.         stmt;
  183.         
  184.     /* No spaces after function names. */
  185.     if (error = function(a1, a2))
  186.         exit(error);
  187.  
  188.     /*
  189.      * Unary operators don't require spaces, binary operators do. Don't
  190.      * use parenthesis unless they're required for precedence, or the
  191.      * statement is really confusing without them.
  192.      */
  193.     a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
  194.     k = !(l & FLAGS);
  195.  
  196.     /*
  197.      * Exits should be 0 on success, and 1 on failure.  Don't denote
  198.      * all the possible exit points, using the integers 1 through 300.
  199.      */
  200.     exit(0);    /* Avoid obvious comments such as "Exit 0 on success." */
  201. }
  202.  
  203. /*
  204.  * If a function type is declared, it should be on a line
  205.  * by itself preceeding the function.
  206.  */
  207. static char *
  208. function(a1, a2, fl, a4)
  209.     int a1, a2, a4;    /* Declare ints, too, don't default them. */
  210.     float fl;    /* List in order declared, as much as possible. */
  211. {
  212.     /*
  213.      * When declaring variables in functions declare them sorted by size,
  214.      * then in alphabetical order; multiple ones per line are okay.  Old
  215.      * style function declarations can go on the same line.  ANSI style
  216.      * function declarations should go in the include file "extern.h".
  217.      * If a line overflows reuse the type keyword.
  218.      *
  219.      * DO NOT initialize variables in the declarations.
  220.      */
  221.     extern u_char one;
  222.     extern char two;
  223.     struct foo three, *four;
  224.     double five;
  225.     int *six, seven, eight();
  226.     char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen;
  227.     char *overflow __P((void));
  228.     void *mymalloc __P((u_int));
  229.  
  230.     /*
  231.      * Casts and sizeof's are not followed by a space.  NULL is any
  232.      * pointer type, and doesn't need to be cast, so use NULL instead
  233.      * of (struct foo *)0 or (struct foo *)NULL.  Also, test pointers
  234.      * against NULL, i.e. use:
  235.      *
  236.      *     (p = f()) == NULL
  237.      * not:
  238.      *    !(p = f())
  239.      *
  240.      * Don't use '!' for tests unless it's a boolean, e.g. use
  241.      * "if (*p == '\0')", not "if (!*p)".
  242.       *
  243.      * Routines returning void * should not have their return values cast
  244.      * to any pointer type.
  245.      *
  246.      * Use err/warn(3), don't roll your own!
  247.      */
  248.     if ((four = malloc(sizeof(struct foo))) == NULL)
  249.         err(1, NULL);
  250.     if ((six = (int *)overflow()) == NULL)
  251.         errx(1, "Number overflowed.");
  252.     return (eight);
  253. }
  254.  
  255. /*
  256.  * Don't use ANSI function declarations unless you absolutely have to,
  257.  * i.e. you're declaring functions with variable numbers of arguments.
  258.  *
  259.  * ANSI function braces look like regular function braces.
  260.  */
  261. function(int a1, int a2)
  262. {
  263.     ...
  264. }
  265.  
  266. /* Variable numbers of arguments should look like this. */
  267. #if __STDC__
  268. #include <stdarg.h>
  269. #else
  270. #include <varargs.h>
  271. #endif
  272.  
  273. void
  274. #if __STDC__
  275. vaf(const char *fmt, ...)
  276. #else
  277. vaf(fmt, va_alist)
  278.     char *fmt;
  279.     va_dcl
  280. #endif
  281. {
  282.     va_list ap;
  283. #if __STDC__
  284.     va_start(ap, fmt);
  285. #else
  286.     va_start(ap);
  287. #endif
  288.     STUFF;
  289.  
  290.     va_end(ap);        /* No return needed for void functions. */
  291. }
  292.  
  293. static void
  294. usage()
  295. {    /* Insert an empty line if the function has no local variables. */
  296.  
  297.     /*
  298.      * Use printf(3), not fputs/puts/putchar/whatever, it's faster and
  299.      * usually cleaner, not to mention avoiding stupid bugs.
  300.      *
  301.      * Usage statements should look like the manual pages.  Options w/o
  302.      * operands come first, in alphabetical order inside a single set of
  303.      * braces.  Followed by options with operands, in alphabetical order,
  304.      * each in braces.  Followed by required arguments in the order they
  305.      * are specified, followed by optional arguments in the order they
  306.      * are specified.  A bar ('|') separates either/or options/arguments,
  307.      * and multiple options/arguments which are specified together are
  308.      * placed in a single set of braces.
  309.      *
  310.      * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n"
  311.      * "usage: f [-a | -b] [-c [-de] [-n number]]\n"
  312.      */
  313.     (void)fprintf(stderr, "usage: f [-ab]\n");
  314.     exit(1);
  315. }
  316.