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