Home | History | Annotate | Line # | Download | only in alpha
STYLE revision 1.1 
      1 $NetBSD: STYLE,v 1.1 1997/04/07 23:57:10 cgd Exp $
      2 
      3 Style guide for NetBSD/alpha kernel files.
      4 
      5 This file is meant to supplement the NetBSD KNF style guide (which covers
      6 most of the rest of the system, and can be found in /usr/share/misc/style).
      7 
      8 
      9 SECTIONS
     10 
     11 	* INCLUDE FILES
     12 	* RCS IDS
     13 	* COMPILATION FLAGS
     14 	* MACRO DEFINITIONS
     15 	* BLOCKS AND EXPRESSIONS
     16 
     17 
     18 INCLUDE FILES
     19 
     20 (1) All C and assembly sources (which are not included by other C or
     21 assembly sources) sources should include <machine/options.h> as the
     22 first header to be included, with a line like:
     23 
     24 #include <machine/options.h>		/* Pull in config options headers */
     25 
     26 (2) All C sources should include <sys/cdefs.h> (after <machine/options.h>,
     27 when it is included, otherwise as the first header to be included), with
     28 a line like:
     29 
     30 #include <sys/cdefs.h>			/* RCS ID & Copyright macro defns */
     31 
     32 (3) Nothing should include <sys/conf.h> directly.  Instead, <machine/conf.h>
     33 should be included.  It includes <sys/conf.h> and provides appropriate
     34 definitions for the machine-dependent devices and macros used by the Alpha
     35 port.
     36 
     37 
     38 RCS IDS
     39 
     40 (1) NetBSD RCS ID tags ($NetBSD: STYLE,v 1.1 1997/04/07 23:57:10 cgd Exp $ tags) in C sources and headers should
     41 appear at the top of the file in a single-line comment of the form
     42 
     43 /*<space>$NetBSD: STYLE,v 1.1 1997/04/07 23:57:10 cgd Exp $<space>*/
     44 
     45 which differs from the normal NetBSD style, in that it uses spaces
     46 rather than tabs to seperate the tag from the comment start and end
     47 delimiters.
     48 
     49 (2) All C sources should include an RCS ID tag which can be compiled into
     50 the binary, with a line like:
     51 
     52 __KERNEL_RCSID(0, "$NetBSD: STYLE,v 1.1 1997/04/07 23:57:10 cgd Exp $");
     53 
     54 after the inclusion of cdefs.h.  C sources which include other C sources
     55 should change the number '0' to a different number, so that it doesn't
     56 conflict with the RCS ID definitios in included sources.  Generation
     57 of these RCS IDs is disabled if the kernel option NO_KERNEL_RCSIDS is
     58 defined.
     59 
     60 
     61 COMPILATION FLAGS
     62 
     63 By default, NetBSD/alpha kernel files are compiled with the following gcc
     64 warning flags:
     65 
     66 	-Werror
     67 	-Wall
     68 	-Wstrict-prototypes
     69 	-Wmissing-prototypes
     70 	-Wno-format
     71 
     72 NetBSD/alpha kernel code should compile cleanly with those flags.  At some
     73 point in the future (when the nonstandard extensions have been removed
     74 from the kernel printf() function), -Wformat will be re-enabled, so sources
     75 should be able to compile with it enabled as well.
     76 
     77 
     78 MACRO DEFINITIONS
     79 
     80 (1) Macros which use C blocks (i.e. are of the form "{ ... expressions
     81 ... }") should always be defined like:
     82 
     83 #define	MACRO(arg1, arg2, argN)					\
     84 do {								\
     85 	...							\
     86 	expressions						\
     87 	...							\
     88 } while (0)
     89 
     90 so that they behave like functions or macros which don't use blocks (e.g.
     91 for the purpose of "if (foo) MACRO(); else ...").
     92 
     93 
     94 BLOCKS AND EXPRESSIONS
     95 
     96 (1) Surround blocks with { and } more often than is absolutely necessary.
     97 For instance:
     98 
     99 	if (foo)
    100 		bar();
    101 
    102 is acceptable, but:
    103 
    104 	if (foo) {
    105 		bar();
    106 	}
    107 
    108 is preferred.  (In contrast, NetBSD KNF says that no braces are to be
    109 used for control statements with zero or one statements.)
    110 
    111 (2) Use extra parentheses when it makes expressions clearer.  For instance,
    112 
    113 	(foo == 10 && bar == 20)
    114 
    115 is acceptable, but:
    116 
    117 	((foo == 10) && (bar == 20))
    118 
    119 is preferred.  (In contrast, NetBSD KNF says to avoid using parentheses
    120 except where necessary unless the expression is very confusing without
    121 them.)
    122