1$NetBSD: STYLE,v 1.6 2002/01/22 00:04:29 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 31RCS IDS 32 33(1) NetBSD RCS ID tags ($NetBSD: STYLE,v 1.6 2002/01/22 00:04:29 wiz 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.6 2002/01/22 00:04:29 wiz 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.6 2002/01/22 00:04:29 wiz 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