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