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