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