version 1.8, 1998/09/01 06:51:09 |
version 1.31, 2005/02/03 00:27:55 |
|
|
/* $NetBSD$ */ |
/* $NetBSD$ */ |
|
|
/* |
/* |
* Style guide for the 4BSD KNF (Kernel Normal Form). |
* The revision control tag appears first, with a blank line after it. |
|
* Copyright text appears after the revision control tag. |
|
*/ |
|
|
|
/* |
|
* The NetBSD source code style guide. |
|
* (Previously known as KNF - Kernel Normal Form). |
* |
* |
* from: @(#)style 1.12 (Berkeley) 3/18/94 |
* from: @(#)style 1.12 (Berkeley) 3/18/94 |
*/ |
*/ |
|
/* |
|
* An indent(1) profile approximating the style outlined in |
|
* this document lives in /usr/share/misc/indent.pro. It is a |
|
* useful tool to assist in converting code to KNF, but indent(1) |
|
* output generated using this profile must not be considered to |
|
* be an authoritative reference. |
|
*/ |
|
|
|
/* |
|
* Source code revision control identifiers appear after any copyright |
|
* text. Use the appropriate macros from <sys/cdefs.h>. Usually only one |
|
* source file per program contains a __COPYRIGHT() section. |
|
* Historic Berkeley code may also have an __SCCSID() section. |
|
* Only one instance of each of these macros can occur in each file. |
|
*/ |
|
#include <sys/cdefs.h> |
|
__COPYRIGHT("@(#) Copyright (c) 2000\n\ |
|
The NetBSD Foundation, inc. All rights reserved.\n"); |
|
__RCSID("$NetBSD$"); |
|
|
/* |
/* |
* VERY important single-line comments look like this. |
* VERY important single-line comments look like this. |
|
|
*/ |
*/ |
|
|
/* |
/* |
* Kernel include files come first; normally, you'll need <sys/types.h> |
* Attempt to wrap lines longer than 80 characters appropriately. |
* OR <sys/param.h>, but not both! <sys/types.h> includes <sys/cdefs.h>, |
* Refer to the examples below for more information. |
* and it's okay to depend on that. |
*/ |
|
|
|
/* |
|
* EXAMPLE HEADER FILE: |
|
* |
|
* A header file should protect itself against multiple inclusion. |
|
* E.g, <sys/socket.h> would contain something like: |
|
*/ |
|
#ifndef _SYS_SOCKET_H_ |
|
#define _SYS_SOCKET_H_ |
|
/* |
|
* Contents of #include file go between the #ifndef and the #endif at the end. |
|
*/ |
|
#endif /* !_SYS_SOCKET_H_ */ |
|
/* |
|
* END OF EXAMPLE HEADER FILE. |
|
*/ |
|
|
|
/* |
|
* Kernel include files come first. |
*/ |
*/ |
#include <sys/types.h> /* Non-local includes in brackets. */ |
#include <sys/types.h> /* Non-local includes in brackets. */ |
|
|
/* If it's a network program, put the network include files next. */ |
/* |
|
* If it's a network program, put the network include files next. |
|
* Group the includes files by subdirectory. |
|
*/ |
#include <net/if.h> |
#include <net/if.h> |
#include <net/if_dl.h> |
#include <net/if_dl.h> |
#include <net/route.h> |
#include <net/route.h> |
|
|
* Then there's a blank line, followed by the /usr include files. |
* Then there's a blank line, followed by the /usr include files. |
* The /usr include files should be sorted! |
* The /usr include files should be sorted! |
*/ |
*/ |
|
#include <assert.h> |
|
#include <errno.h> |
#include <stdio.h> |
#include <stdio.h> |
|
#include <stdlib.h> |
|
|
/* |
/* |
* Global pathnames are defined in /usr/include/paths.h. Pathnames local |
* Global pathnames are defined in /usr/include/paths.h. Pathnames local |
|
|
#include <paths.h> |
#include <paths.h> |
|
|
/* Then, there's a blank line, and the user include files. */ |
/* Then, there's a blank line, and the user include files. */ |
#include "pathnames.h" /* Local includes in double quotes. */ |
#include "pathnames.h" /* Local includes in double quotes. */ |
|
|
/* |
/* |
* ANSI function declarations for private functions (i.e. functions not used |
* ANSI function declarations for private functions (i.e. functions not used |
* elsewhere) go at the top of the source module. Use the __P macro from |
* elsewhere) and the main() function go at the top of the source module. |
* the include file <sys/cdefs.h>. Only the kernel has a name associated with |
* Don't associate a name with the types. I.e. use: |
* the types, i.e. in the kernel use: |
* void function(int); |
* |
* Use your discretion on indenting between the return type and the name, and |
* void function __P((int a)); |
* how to wrap a prototype too long for a single line. In the latter case, |
* |
* lining up under the initial left parenthesis may be more readable. |
* in user land use: |
* In any case, consistency is important! |
* |
*/ |
* void function __P((int)); |
static char *function(int, int, float, int); |
*/ |
static int dirinfo(const char *, struct stat *, struct dirent *, |
static char *function __P((int, const char *)); |
struct statfs *, int *, char **[]); |
static void usage __P((void)); |
static void usage(void); |
|
int main(int, char *[]); |
|
|
/* |
/* |
* Macros are capitalized, parenthesized, and should avoid side-effects. |
* Macros are capitalized, parenthesized, and should avoid side-effects. |
|
* Spacing before and after the macro name may be any whitespace, though |
|
* use of TABs should be consistent through a file. |
* If they are an inline expansion of a function, the function is defined |
* If they are an inline expansion of a function, the function is defined |
* all in lowercase, the macro has the same name all in uppercase. If the |
* all in lowercase, the macro has the same name all in uppercase. |
* macro needs more than a single line, use braces. Right-justify the |
* If the macro is an expression, wrap the expression in parenthesis. |
* backslashes, it makes it easier to read. |
* If the macro is more than a single statement, use ``do { ... } while (0)'', |
*/ |
* so that a trailing semicolon works. Right-justify the backslashes; it |
#define MACRO(x, y) { \ |
* makes it easier to read. The CONSTCOND comment is to satisfy lint(1). |
variable = (x) + (y); \ |
*/ |
(y) += 2; \ |
#define MACRO(v, w, x, y) \ |
} |
do { \ |
|
v = (x) + (y); \ |
/* Enum types are capitalized. */ |
w = (y) + 2; \ |
enum enumtype { ONE, TWO } et; |
} while (/* CONSTCOND */ 0) |
|
|
/* |
#define DOUBLE(x) ((x) * 2) |
* When declaring variables in structures, declare them sorted by use, then |
|
* by size, and then by alphabetical order. The first category normally |
/* Enum types are capitalized. No comma on the last element. */ |
* doesn't apply, but there are exceptions. Each one gets its own line. |
enum enumtype { |
* Put a tab after the first word, i.e. use "int^Ix;" and "struct^Ifoo *x;". |
ONE, |
|
TWO |
|
} et; |
|
|
|
/* |
|
* When declaring variables in structures, declare them organized by use in |
|
* a manner to attempt to minimize memory wastage because of compiler alignment |
|
* issues, then by size, and then by alphabetical order. E.g, don't use |
|
* ``int a; char *b; int c; char *d''; use ``int a; int b; char *c; char *d''. |
|
* Each variable gets its own type and line, although an exception can be made |
|
* when declaring bitfields (to clarify that it's part of the one bitfield). |
|
* Note that the use of bitfields in general is discouraged. |
* |
* |
* Major structures should be declared at the top of the file in which they |
* Major structures should be declared at the top of the file in which they |
* are used, or in separate header files, if they are used in multiple |
* are used, or in separate header files, if they are used in multiple |
* source files. Use of the structures should be by separate declarations |
* source files. Use of the structures should be by separate declarations |
* and should be "extern" if they are declared in a header file. |
* and should be "extern" if they are declared in a header file. |
|
* |
|
* It may be useful to use a meaningful prefix for each member name. |
|
* E.g, for ``struct softc'' the prefix could be ``sc_''. |
*/ |
*/ |
struct foo { |
struct foo { |
struct foo *next; /* List of active foo */ |
struct foo *next; /* List of active foo */ |
struct mumble amumble; /* Comment for mumble */ |
struct mumble amumble; /* Comment for mumble */ |
int bar; |
int bar; |
|
unsigned int baz:1, /* Bitfield; line up entries if desired */ |
|
fuz:5, |
|
zap:2; |
|
uint8_t flag; |
}; |
}; |
struct foo *foohead; /* Head of global foo list */ |
struct foo *foohead; /* Head of global foo list */ |
|
|
/* Make the structure name match the typedef. */ |
/* Make the structure name match the typedef. */ |
typedef struct _bar { |
typedef struct BAR { |
int level; |
int level; |
} BAR; |
} BAR; |
|
|
/* |
/* |
* All major routines should have a comment briefly describing what |
* All major routines should have a comment briefly describing what |
* they do. The comment before the "main" routine should describe |
* they do. The comment before the "main" routine should describe |
* what the program does. |
* what the program does. |
*/ |
*/ |
int |
int |
main(argc, argv) |
main(int argc, char *argv[]) |
int argc; |
|
char *argv[]; |
|
{ |
{ |
extern char *optarg; |
|
extern int optind; |
|
long num; |
long num; |
int ch; |
int ch; |
char *ep; |
char *ep; |
|
|
/* |
/* |
|
* At the start of main(), call setprogname() to set the program |
|
* name. This does nothing on NetBSD, but increases portability |
|
* to other systems. |
|
*/ |
|
setprogname(argv[0]); |
|
|
|
/* |
* For consistency, getopt should be used to parse options. Options |
* For consistency, getopt should be used to parse options. Options |
* should be sorted in the getopt call and the switch statement, unless |
* should be sorted in the getopt call and the switch statement, unless |
* parts of the switch cascade. Elements in a switch statement that |
* parts of the switch cascade. Elements in a switch statement that |
Line 123 main(argc, argv) |
|
Line 197 main(argc, argv) |
|
* should be checked for accuracy. Code that cannot be reached should |
* should be checked for accuracy. Code that cannot be reached should |
* have a NOTREACHED comment. |
* have a NOTREACHED comment. |
*/ |
*/ |
while ((ch = getopt(argc, argv, "abn")) != -1) |
while ((ch = getopt(argc, argv, "abn")) != -1) { |
switch (ch) { /* Indent the switch. */ |
switch (ch) { /* Indent the switch. */ |
case 'a': /* Don't indent the case. */ |
case 'a': /* Don't indent the case. */ |
aflag = 1; |
aflag = 1; |
Line 132 main(argc, argv) |
|
Line 206 main(argc, argv) |
|
bflag = 1; |
bflag = 1; |
break; |
break; |
case 'n': |
case 'n': |
|
errno = 0; |
num = strtol(optarg, &ep, 10); |
num = strtol(optarg, &ep, 10); |
if (num <= 0 || *ep != '\0') |
if (num <= 0 || *ep != '\0' || (errno == ERANGE && |
err("illegal number -- %s", optarg); |
(num == LONG_MAX || num == LONG_MIN)) ) |
|
errx(1, "illegal number -- %s", optarg); |
break; |
break; |
case '?': |
case '?': |
default: |
default: |
usage(); |
usage(); |
/* NOTREACHED */ |
/* NOTREACHED */ |
} |
} |
|
} |
argc -= optind; |
argc -= optind; |
argv += optind; |
argv += optind; |
|
|
/* |
/* |
* Space after keywords (while, for, return, switch). No braces are |
* Space after keywords (while, for, return, switch). No braces are |
* used for control statements with zero or only a single statement. |
* used for control statements with zero or only a single statement, |
|
* unless it's a long statement. |
* |
* |
* Forever loops are done with for's, not while's. |
* Forever loops are done with for's, not while's. |
*/ |
*/ |
for (p = buf; *p != '\0'; ++p); |
for (p = buf; *p != '\0'; ++p) |
|
continue; /* Explicit no-op */ |
for (;;) |
for (;;) |
stmt; |
stmt; |
|
|
/* |
/* |
* Parts of a for loop may be left empty. Don't put declarations |
* Parts of a for loop may be left empty. Don't put declarations |
* inside blocks unless the routine is unusually complicated. |
* inside blocks unless the routine is unusually complicated. |
Line 165 main(argc, argv) |
|
Line 244 main(argc, argv) |
|
|
|
/* Second level indents are four spaces. */ |
/* Second level indents are four spaces. */ |
while (cnt < 20) |
while (cnt < 20) |
z = a + really + long + statment + that + needs + two lines + |
z = a + really + long + statement + that + needs + two lines + |
gets + indented + four + spaces + on + the + second + |
gets + indented + four + spaces + on + the + second + |
and + subsequent + lines; |
and + subsequent + lines; |
|
|
/* |
/* |
* Closing and opening braces go on the same line as the else. |
* Closing and opening braces go on the same line as the else. |
* Don't add braces that aren't necessary. |
* Don't add braces that aren't necessary except in cases where |
|
* there are ambiguity or readability issues. |
*/ |
*/ |
if (test) |
if (test) { |
stmt; |
/* |
else if (bar) { |
* I have a long comment here. |
|
*/ |
|
#ifdef zorro |
|
z = 1; |
|
#else |
|
b = 3; |
|
#endif |
|
} else if (bar) { |
stmt; |
stmt; |
stmt; |
stmt; |
} else |
} else |
stmt; |
stmt; |
|
|
/* No spaces after function names. */ |
/* No spaces after function names. */ |
if (error = function(a1, a2)) |
if ((result = function(a1, a2, a3, a4)) == NULL) |
exit(error); |
exit(1); |
|
|
/* |
/* |
* Unary operators don't require spaces, binary operators do. Don't |
* Unary operators don't require spaces, binary operators do. |
* use parenthesis unless they're required for precedence, or the |
* Don't excessively use parenthesis, but they should be used if |
* statement is really confusing without them. |
* statement is really confusing without them, such as: |
|
* a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; |
*/ |
*/ |
a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; |
a = ((b->c[0] + ~d == (e || f)) || (g && h)) ? i : (j >> 1); |
k = !(l & FLAGS); |
k = !(l & FLAGS); |
|
|
/* |
/* |
* Exits should be 0 on success, and 1 on failure. Don't denote |
* Exits should be EXIT_SUCCESS on success, and EXIT_FAILURE on |
* all the possible exit points, using the integers 1 through 300. |
* failure. Don't denote all the possible exit points, using the |
|
* integers 1 through 127. Avoid obvious comments such as "Exit |
|
* 0 on success.". Since main is a function that returns an int, |
|
* prefer returning from it, than calling exit. |
*/ |
*/ |
exit(0); /* Avoid obvious comments such as "Exit 0 on success." */ |
return EXIT_SUCCESS; |
} |
} |
|
|
/* |
/* |
* The function type must be declared on a line by itself |
* The function type must be declared on a line by itself |
* preceeding the function. |
* preceding the function. |
*/ |
*/ |
static char * |
static char * |
function(a1, a2, fl, a4) |
function(int a1, int a2, float fl, int a4) |
int a1, a2, a4; /* Declare ints, too, don't default them. */ |
|
float fl; /* List in order declared, as much as possible. */ |
|
{ |
{ |
/* |
/* |
* When declaring variables in functions declare them sorted by size, |
* When declaring variables in functions declare them sorted by size, |
* then in alphabetical order; multiple ones per line are okay. Old |
* then in alphabetical order; multiple ones per line are okay. |
* style function declarations can go on the same line. ANSI style |
* Function prototypes should go in the include file "extern.h". |
* function declarations should go in the include file "extern.h". |
|
* If a line overflows reuse the type keyword. |
* If a line overflows reuse the type keyword. |
* |
* |
* DO NOT initialize variables in the declarations. |
* DO NOT initialize variables in the declarations. |
*/ |
*/ |
|
extern uint32_t zero; |
extern u_char one; |
extern u_char one; |
extern char two; |
extern char two; |
struct foo three, *four; |
struct foo three, *four; |
double five; |
double five; |
int *six, seven, eight(); |
int *six, seven; |
char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen, sixteen; |
char *eight, *nine, ten, eleven, twelve, thirteen; |
char *overflow __P((void)); |
char fourteen, fifteen, sixteen; |
void *mymalloc __P((u_int)); |
|
|
|
/* |
/* |
* Casts and sizeof's are not followed by a space. NULL is any |
* Casts and sizeof's are not followed by a space. NULL is any |
* pointer type, and doesn't need to be cast, so use NULL instead |
* pointer type, and doesn't need to be cast, so use NULL instead |
* of (struct foo *)0 or (struct foo *)NULL. Also, test pointers |
* of (struct foo *)0 or (struct foo *)NULL. Also, test pointers |
* against NULL, i.e. use: |
* against NULL. I.e. use: |
* |
* |
* (p = f()) == NULL |
* (p = f()) == NULL |
* not: |
* not: |
* !(p = f()) |
* !(p = f()) |
* |
* |
* Don't use '!' for tests unless it's a boolean, e.g. use |
* Don't use `!' for tests unless it's a boolean. |
* "if (*p == '\0')", not "if (!*p)". |
* E.g. use "if (*p == '\0')", not "if (!*p)". |
* |
* |
* Routines returning void * should not have their return values cast |
* Routines returning ``void *'' should not have their return |
* to any pointer type. |
* values cast to more specific pointer types. |
* |
* |
* Use err/warn(3), don't roll your own! |
* Use err/warn(3), don't roll your own! |
*/ |
*/ |
Line 249 function(a1, a2, fl, a4) |
|
Line 337 function(a1, a2, fl, a4) |
|
err(1, NULL); |
err(1, NULL); |
if ((six = (int *)overflow()) == NULL) |
if ((six = (int *)overflow()) == NULL) |
errx(1, "Number overflowed."); |
errx(1, "Number overflowed."); |
return (eight); |
|
|
/* No parentheses are needed around the return value. */ |
|
return eight; |
} |
} |
|
|
/* |
/* |
* Don't use ANSI function declarations unless you absolutely have to, |
* Use ANSI function declarations. ANSI function braces look like |
* i.e. you're declaring functions with variable numbers of arguments. |
* old-style (K&R) function braces. |
* |
* As per the wrapped prototypes, use your discretion on how to format |
* ANSI function braces look like regular function braces. |
* the subsequent lines. |
*/ |
*/ |
function(int a1, int a2) |
static int |
{ |
dirinfo(const char *p, struct stat *sb, struct dirent *de, struct statfs *sf, |
... |
int *rargc, char **rargv[]) |
|
{ /* Insert an empty line if the function has no local variables. */ |
|
|
|
/* |
|
* In system libraries, catch obviously invalid function arguments |
|
* using _DIAGASSERT(3). |
|
*/ |
|
_DIAGASSERT(p != NULL); |
|
_DIAGASSERT(filedesc != -1); |
|
|
|
if (stat(p, sb) < 0) |
|
err(1, "Unable to stat %s", p); |
|
|
|
/* |
|
* To printf 64 bit quantities, use %ll and cast to (long long). |
|
*/ |
|
(void)printf("The size of %s is %lld\n", p, (long long)sb->st_size); |
} |
} |
|
|
/* Variable numbers of arguments should look like this. */ |
/* |
#if __STDC__ |
* Functions that support variable numbers of arguments should look like this. |
|
* (With the #include <stdarg.h> appearing at the top of the file with the |
|
* other include files). |
|
*/ |
#include <stdarg.h> |
#include <stdarg.h> |
#else |
|
#include <varargs.h> |
|
#endif |
|
|
|
void |
void |
#if __STDC__ |
|
vaf(const char *fmt, ...) |
vaf(const char *fmt, ...) |
#else |
|
vaf(fmt, va_alist) |
|
char *fmt; |
|
va_dcl |
|
#endif |
|
{ |
{ |
va_list ap; |
va_list ap; |
#if __STDC__ |
|
va_start(ap, fmt); |
va_start(ap, fmt); |
#else |
|
va_start(ap); |
|
#endif |
|
STUFF; |
STUFF; |
|
va_end(ap); |
va_end(ap); /* No return needed for void functions. */ |
/* No return needed for void functions. */ |
} |
} |
|
|
static void |
static void |
usage() |
usage(void) |
{ /* Insert an empty line if the function has no local variables. */ |
{ |
|
|
/* |
/* |
* Use printf(3), not fputs/puts/putchar/whatever, it's faster and |
* Use printf(3), not fputs/puts/putchar/whatever, it's faster and |
* usually cleaner, not to mention avoiding stupid bugs. |
* usually cleaner, not to mention avoiding stupid bugs. |
|
* Use snprintf(3) or strlcpy(3)/strlcat(3) instead of sprintf(3); |
|
* again to avoid stupid bugs. |
* |
* |
* Usage statements should look like the manual pages. Options w/o |
* Usage statements should look like the manual pages. Options w/o |
* operands come first, in alphabetical order inside a single set of |
* operands come first, in alphabetical order inside a single set of |
* braces. Followed by options with operands, in alphabetical order, |
* braces. Followed by options with operands, in alphabetical order, |
* each in braces. Followed by required arguments in the order they |
* each in braces. Followed by required arguments in the order they |
* are specified, followed by optional arguments in the order they |
* are specified, followed by optional arguments in the order they |
* are specified. A bar ('|') separates either/or options/arguments, |
* are specified. A bar (`|') separates either/or options/arguments, |
* and multiple options/arguments which are specified together are |
* and multiple options/arguments which are specified together are |
* placed in a single set of braces. |
* placed in a single set of braces. |
* |
* |
|
* Use getprogname() instead of hardcoding the program name. |
|
* |
* "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n" |
* "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\n" |
* "usage: f [-a | -b] [-c [-de] [-n number]]\n" |
* "usage: f [-a | -b] [-c [-de] [-n number]]\n" |
*/ |
*/ |
(void)fprintf(stderr, "usage: f [-ab]\n"); |
(void)fprintf(stderr, "usage: %s [-ab]\n", getprogname()); |
exit(1); |
exit(1); |
} |
} |