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