style revision 1.15
1/* $NetBSD: style,v 1.15 2000/09/04 08:01:16 lukem Exp $ */ 2 3/* 4 * The revision control tag appears first, with a blank line after it. 5 * Copyright text appears after the revision control tag. 6 */ 7 8/* 9 * The NetBSD source code style guide. 10 * (Previously known as KNF - Kernel Normal Form). 11 * 12 * from: @(#)style 1.12 (Berkeley) 3/18/94 13 */ 14/* 15 * An indent(1) profile approximating the style outlined in 16 * this document lives in /usr/share/misc/indent.pro. It is a 17 * useful tool to assist in converting code to KNF, but indent(1) 18 * output generated using this profile must not be considered to 19 * be an authoritative reference. 20 */ 21 22/* 23 * Source code revision control identifiers appear after any copyright 24 * text. Use the appropriate macros from <sys/cdefs.h>. Usually only one 25 * source file per program contains a __COPYRIGHT() section. 26 * Historic Berkeley code may also have an __SCCSID() section. 27 * Only one instance of each of these macros can occur in each file. 28 */ 29#include <sys/cdefs.h> 30#ifndef __lint 31__COPYRIGHT("@(#) Copyright (c) 2000\n\ 32 The NetBSD Foundation, inc. All rights reserved.\n"); 33__RCSID("$NetBSD: style,v 1.15 2000/09/04 08:01:16 lukem Exp $"); 34#endif /* !__lint */ 35 36/* 37 * VERY important single-line comments look like this. 38 */ 39 40/* Most single-line comments look like this. */ 41 42/* 43 * Multi-line comments look like this. Make them real sentences. Fill 44 * them so they look like real paragraphs. 45 */ 46 47/* 48 * Attempt to wrap lines longer than 80 characters appropriately. 49 * Refer to the examples below for more information. 50 */ 51 52/* 53 * EXAMPLE HEADER FILE: 54 * 55 * A header file should protect itself against multiple inclusion. 56 * E.g, <sys/socket.h> would contain something like: 57 */ 58#ifndef _SYS_SOCKET_H_ 59#define _SYS_SOCKET_H_ 60/* 61 * Contents of #include file go between the #ifndef and the #endif at the end. 62 */ 63#endif /* !_SYS_SOCKET_H_ */ 64/* 65 * END OF EXAMPLE HEADER FILE. 66 */ 67 68/* 69 * Kernel include files come first. 70 */ 71#include <sys/types.h> /* Non-local includes in brackets. */ 72 73/* 74 * If it's a network program, put the network include files next. 75 * Group the includes files by subdirectory. 76 */ 77#include <net/if.h> 78#include <net/if_dl.h> 79#include <net/route.h> 80#include <netinet/in.h> 81#include <protocols/rwhod.h> 82 83/* 84 * Then there's a blank line, followed by the /usr include files. 85 * The /usr include files should be sorted! 86 */ 87#include <stdio.h> 88 89/* 90 * Global pathnames are defined in /usr/include/paths.h. Pathnames local 91 * to the program go in pathnames.h in the local directory. 92 */ 93#include <paths.h> 94 95/* Then, there's a blank line, and the user include files. */ 96#include "pathnames.h" /* Local includes in double quotes. */ 97 98/* 99 * ANSI function declarations for private functions (i.e. functions not used 100 * elsewhere) and the main() function go at the top of the source module. 101 * Don't associate a name with the types. I.e. use: 102 * void function(int); 103 * Use your discretion on indenting between the return type and the name, and 104 * how to wrap a prototype too long for a single line. In the latter case, 105 * lining up under the initial left parenthesis may be more readable. 106 * In any case, consistency is important! 107 */ 108static char *function(int, int, float, int); 109static int dirinfo(const char *, struct stat *, struct dirent *, 110 struct statfs *, int *, char **[]); 111static void usage(void); 112int main(int, char *[]); 113 114/* 115 * Macros are capitalized, parenthesized, and should avoid side-effects. 116 * If they are an inline expansion of a function, the function is defined 117 * all in lowercase, the macro has the same name all in uppercase. 118 * If the macro is an expression, wrap the expression in parenthesis. 119 * If the macro is more than a single statement, use ``do { ... } while (0)'', 120 * so that a trailing semicolon works. Right-justify the backslashes; it 121 * makes it easier to read. The CONSTCOND comment is to satisfy lint(1). 122 */ 123#define MACRO(v, w, x, y) \ 124do { \ 125 v = (x) + (y); \ 126 w = (y) + 2; \ 127} while (/* CONSTCOND */ 0) 128 129#define DOUBLE(x) ((x) * 2) 130 131/* Enum types are capitalized. No comma on the last element. */ 132enum enumtype { 133 ONE, 134 TWO 135} et; 136 137/* 138 * When declaring variables in structures, declare them organised by use in 139 * a manner to attempt to minimise memory wastage because of compiler alignment 140 * issues, then by size, and then by alphabetical order. E.g, don't use 141 * ``int a; char *b; int c; char *d''; use ``int a; int b; char *c; char *d''. 142 * Each variable gets its own type and line, although an exception can be made 143 * when declaring bitfields (to clarify that it's part of the one bitfield). 144 * Note that the use of bitfields in general is discouraged. 145 * 146 * Major structures should be declared at the top of the file in which they 147 * are used, or in separate header files, if they are used in multiple 148 * source files. Use of the structures should be by separate declarations 149 * and should be "extern" if they are declared in a header file. 150 * 151 * It may be useful to use a meaningful prefix for each member name. 152 * E.g, for ``struct softc'' the prefix could be ``sc_''. 153 */ 154struct foo { 155 struct foo *next; /* List of active foo */ 156 struct mumble amumble; /* Comment for mumble */ 157 int bar; 158 unsigned int baz:1, /* Bitfield; line up entries if desired */ 159 fuz:5, 160 zap:2; 161 u_int8_t flag; 162}; 163struct foo *foohead; /* Head of global foo list */ 164 165/* Make the structure name match the typedef. */ 166typedef struct BAR { 167 int level; 168} BAR; 169 170/* 171 * All major routines should have a comment briefly describing what 172 * they do. The comment before the "main" routine should describe 173 * what the program does. 174 */ 175int 176main(int argc, char *argv[]) 177{ 178 long num; 179 int ch; 180 char *ep; 181 182 /* 183 * For consistency, getopt should be used to parse options. Options 184 * should be sorted in the getopt call and the switch statement, unless 185 * parts of the switch cascade. Elements in a switch statement that 186 * cascade should have a FALLTHROUGH comment. Numerical arguments 187 * should be checked for accuracy. Code that cannot be reached should 188 * have a NOTREACHED comment. 189 */ 190 while ((ch = getopt(argc, argv, "abn")) != -1) { 191 switch (ch) { /* Indent the switch. */ 192 case 'a': /* Don't indent the case. */ 193 aflag = 1; 194 /* FALLTHROUGH */ 195 case 'b': 196 bflag = 1; 197 break; 198 case 'n': 199 num = strtol(optarg, &ep, 10); 200 if (num <= 0 || *ep != '\0') 201 errx(1, "illegal number -- %s", optarg); 202 break; 203 case '?': 204 default: 205 usage(); 206 /* NOTREACHED */ 207 } 208 } 209 argc -= optind; 210 argv += optind; 211 212 /* 213 * Space after keywords (while, for, return, switch). No braces are 214 * used for control statements with zero or only a single statement, 215 * unless it's a long statement. 216 * 217 * Forever loops are done with for's, not while's. 218 */ 219 for (p = buf; *p != '\0'; ++p) 220 continue; /* Explicit no-op */ 221 for (;;) 222 stmt; 223 224 /* 225 * Parts of a for loop may be left empty. Don't put declarations 226 * inside blocks unless the routine is unusually complicated. 227 */ 228 for (; cnt < 15; cnt++) { 229 stmt1; 230 stmt2; 231 } 232 233 /* Second level indents are four spaces. */ 234 while (cnt < 20) 235 z = a + really + long + statment + that + needs + two lines + 236 gets + indented + four + spaces + on + the + second + 237 and + subsequent + lines; 238 239 /* 240 * Closing and opening braces go on the same line as the else. 241 * Don't add braces that aren't necessary except in cases where 242 * there are ambiguity or readability issues. 243 */ 244 if (test) { 245 /* 246 * I have a long comment here. 247 */ 248#ifdef zorro 249 z = 1; 250#else 251 b = 3; 252#endif 253 } else if (bar) { 254 stmt; 255 stmt; 256 } else 257 stmt; 258 259 /* No spaces after function names. */ 260 if ((result = function(a1, a2, a3, a4)) == NULL) 261 exit(1); 262 263 /* 264 * Unary operators don't require spaces, binary operators do. 265 * Don't excessively use parenthesis, but they should be used if 266 * statement is really confusing without them, such as: 267 * a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; 268 */ 269 a = ((b->c[0] + ~d == (e || f)) || (g && h)) ? i : (j >> 1); 270 k = !(l & FLAGS); 271 272 /* 273 * Exits should be 0 on success, and 1 on failure. Don't denote 274 * all the possible exit points, using the integers 1 through 300. 275 * Avoid obvious comments such as "Exit 0 on success." 276 */ 277 exit(0); 278} 279 280/* 281 * The function type must be declared on a line by itself 282 * preceeding the function. 283 */ 284static char * 285function(int a1, int a2, float fl, int a4) 286{ 287 /* 288 * When declaring variables in functions declare them sorted by size, 289 * then in alphabetical order; multiple ones per line are okay. 290 * Function prototypes should go in the include file "extern.h". 291 * If a line overflows reuse the type keyword. 292 * 293 * DO NOT initialize variables in the declarations. 294 */ 295 extern u_char one; 296 extern char two; 297 struct foo three, *four; 298 double five; 299 int *six, seven; 300 char *eight, *nine, ten, eleven, twelve, thirteen; 301 char fourteen, fifteen, sixteen; 302 303 /* 304 * Casts and sizeof's are not followed by a space. NULL is any 305 * pointer type, and doesn't need to be cast, so use NULL instead 306 * of (struct foo *)0 or (struct foo *)NULL. Also, test pointers 307 * against NULL. I.e. use: 308 * 309 * (p = f()) == NULL 310 * not: 311 * !(p = f()) 312 * 313 * Don't use `!' for tests unless it's a boolean. 314 * E.g. use "if (*p == '\0')", not "if (!*p)". 315 * 316 * Routines returning void * should not have their return values cast 317 * to any pointer type. 318 * 319 * Use err/warn(3), don't roll your own! 320 */ 321 if ((four = malloc(sizeof(struct foo))) == NULL) 322 err(1, NULL); 323 if ((six = (int *)overflow()) == NULL) 324 errx(1, "Number overflowed."); 325 return (eight); 326} 327 328/* 329 * Use ANSI function declarations. ANSI function braces look like 330 * old-style (K&R) function braces. 331 * As per the wrapped prototypes, use your discretion on how to format 332 * the subsequent lines. 333 */ 334static int 335dirinfo(const char *p, struct stat *sb, struct dirent *de, struct statfs *sf, 336 int *rargc, char **rargv[]) 337{ /* Insert an empty line if the function has no local variables. */ 338 339 if (stat(p, sb) < 0) 340 err(1, "Unable to stat %s", p); 341 342 /* 343 * To printf 64 bit quantities, use %ll and cast to (long long). 344 */ 345 printf("The size of %s is %lld\n", p, (long long)sb->st_size); 346} 347 348/* 349 * Functions that support variable numbers of arguments should look like this. 350 * (With the #include <stdarg.h> appearing at the top of the file with the 351 * other include files). 352 */ 353#include <stdarg.h> 354 355void 356vaf(const char *fmt, ...) 357{ 358 va_list ap; 359 360 va_start(ap, fmt); 361 STUFF; 362 va_end(ap); 363 /* No return needed for void functions. */ 364} 365 366static void 367usage(void) 368{ 369 extern char *__progname; /* Provided by NetBSD's crt0.o */ 370 371 /* 372 * Use printf(3), not fputs/puts/putchar/whatever, it's faster and 373 * usually cleaner, not to mention avoiding stupid bugs. 374 * Use snprintf(3) or strlcpy(3)/strlcat(3) instead of sprintf(3); 375 * again to avoid stupid bugs. 376 * 377 * Usage statements should look like the manual pages. Options w/o 378 * operands come first, in alphabetical order inside a single set of 379 * braces. Followed by options with operands, in alphabetical order, 380 * each in braces. Followed by required arguments in the order they 381 * are specified, followed by optional arguments in the order they 382 * are specified. A bar (`|') separates either/or options/arguments, 383 * and multiple options/arguments which are specified together are 384 * placed in a single set of braces. 385 * 386 * Use __progname (from crt0.o) instead of hardcoding the program name. 387 * 388 * "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n" 389 * "usage: f [-a | -b] [-c [-de] [-n number]]\n" 390 */ 391 (void)fprintf(stderr, "usage: %s [-ab]\n", __progname); 392 exit(1); 393} 394