352 lines
11 KiB
Groff
352 lines
11 KiB
Groff
.Dd December 14, 1995
|
|
.Dt STYLE 9
|
|
.Os FreeBSD 2.2
|
|
.Sh NAME
|
|
.Nm STYLE
|
|
.Nd "Kernel source file style guide"
|
|
.Sh DESCRIPTION
|
|
This file contains an example of the preferred style for kernel source
|
|
files in the FreeBSD source tree.
|
|
|
|
.Bd -literal
|
|
/*
|
|
* Style guide for the 4BSD KNF (Kernel Normal Form).
|
|
*
|
|
* @(#)style 1.14 (Berkeley) 4/28/95
|
|
*/
|
|
|
|
/*
|
|
* VERY important single-line comments look like this.
|
|
*/
|
|
|
|
/* Most single-line comments look like this. */
|
|
|
|
/*
|
|
* Multi-line comments look like this. Make them real sentences.
|
|
* Fill them so they look like real paragraphs.
|
|
*/
|
|
|
|
/*
|
|
* Kernel include files come first; normally, you'll need
|
|
* <sys/types.h> OR <sys/param.h>, but not both! <sys/types.h>
|
|
* includes <sys/cdefs.h>, and it's okay to depend on that.
|
|
*/
|
|
#include <sys/types.h> /* Non-local includes in brackets. */
|
|
|
|
/* If it's a network program, put the network include files next. */
|
|
#include <net/if.h>
|
|
#include <net/if_dl.h>
|
|
#include <net/route.h>
|
|
#include <netinet/in.h>
|
|
#include <protocols/rwhod.h>
|
|
|
|
/*
|
|
* Then there's a blank line, followed by the /usr include files.
|
|
* The /usr include files should be sorted!
|
|
*/
|
|
#include <stdio.h>
|
|
|
|
/*
|
|
* Global pathnames are defined in /usr/include/paths.h. Pathnames
|
|
* local to the program go in pathnames.h in the local directory.
|
|
*/
|
|
#include <paths.h>
|
|
|
|
/* Then, there's a blank line, and the user include files. */
|
|
#include "pathnames.h" /* Local includes in double quotes. */
|
|
|
|
/*
|
|
* Macros are capitalized, parenthesized, and should avoid side-
|
|
* effects. 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 macro needs more than a single
|
|
* line, use braces. Right-justify the backslashes, it makes it
|
|
* easier to read.
|
|
*/
|
|
#define MACRO(x, y) { \e
|
|
variable = (x) + (y); \e
|
|
(y) += 2; \e
|
|
}
|
|
|
|
/* Enum types are capitalized. */
|
|
enum enumtype { ONE, TWO } et;
|
|
|
|
/*
|
|
* When declaring variables in structures, declare them sorted by use,
|
|
* then by size, and then by alphabetical order. The first category
|
|
* normally doesn't apply, but there are exceptions. Each one gets
|
|
* its own line.
|
|
* Put a tab after the first word, i.e. use
|
|
* "int^Ix;" and "struct^Ifoo *x;".
|
|
*
|
|
* 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 source files. Use of the structures should be by separate
|
|
* declarations and should be "extern" if they are declared in a header
|
|
* file.
|
|
*/
|
|
struct foo {
|
|
struct foo *next; /* List of active foo */
|
|
struct mumble amumble; /* Comment for mumble */
|
|
int bar;
|
|
};
|
|
struct foo *foohead; /* Head of global foo list */
|
|
|
|
/* Make the structure name match the typedef. */
|
|
typedef struct _bar {
|
|
int level;
|
|
} BAR;
|
|
|
|
/*
|
|
* All functions are prototyped somewhere.
|
|
*
|
|
* Function prototypes for private functions (i.e. functions
|
|
* not used elsewhere) go at the top of the first source module.
|
|
*
|
|
* Functions used from other parts of the kernel are prototyped
|
|
* in the relevant include file.
|
|
*
|
|
* Only use the __P macro from the include file <sys/cdefs.h> if the
|
|
* source file in general is compilable with an K&R Old testament
|
|
* compiler.
|
|
*
|
|
* Only the kernel has a name associated with the types, i.e. in the
|
|
* kernel use:
|
|
*
|
|
* void function __P((int fd));
|
|
*
|
|
* in user land use:
|
|
*
|
|
* void function __P((int));
|
|
*/
|
|
static char *function __P((int, const char *));
|
|
static void usage __P((void));
|
|
|
|
/*
|
|
* All major routines should have a comment briefly describing what
|
|
* they do. The comment before the "main" routine should describe
|
|
* what the program does.
|
|
*/
|
|
int
|
|
main(argc, argv)
|
|
int argc;
|
|
char *argv[];
|
|
{
|
|
extern char *optarg;
|
|
extern int optind;
|
|
long num;
|
|
int ch;
|
|
char *ep;
|
|
|
|
/*
|
|
* For consistency, getopt should be used to parse options.
|
|
* Options should be sorted in the getopt call and the switch
|
|
* statement, unless parts of the switch cascade. Elements
|
|
* in a switch statement that cascade should have a FALLTHROUGH
|
|
* comment. Numerical arguments should be checked for accuracy.
|
|
* Code that cannot be reached should have a NOTREACHED comment.
|
|
*/
|
|
while ((ch = getopt(argc, argv, "abn")) != EOF)
|
|
switch (ch) { /* Indent the switch. */
|
|
case 'a': /* Don't indent the case. */
|
|
aflag = 1;
|
|
/* FALLTHROUGH */
|
|
case 'b':
|
|
bflag = 1;
|
|
break;
|
|
case 'n':
|
|
num = strtol(optarg, &ep, 10);
|
|
if (num <= 0 || *ep != '\e0')
|
|
err("illegal number -- %s", optarg);
|
|
break;
|
|
case '?':
|
|
default:
|
|
usage();
|
|
/* NOTREACHED */
|
|
}
|
|
argc -= optind;
|
|
argv += optind;
|
|
|
|
/*
|
|
* Space after keywords (while, for, return, switch).
|
|
* No braces are used for control statements with zero or only
|
|
* a single statement.
|
|
*
|
|
* Forever loops are done with for's, not while's.
|
|
*/
|
|
for (p = buf; *p != '\e0'; ++p);
|
|
for (;;)
|
|
stmt;
|
|
|
|
/*
|
|
* Parts of a for loop may be left empty. Don't put
|
|
* declarations inside blocks unless the routine is unusually
|
|
* complicated.
|
|
*/
|
|
for (; cnt < 15; cnt++) {
|
|
stmt1;
|
|
stmt2;
|
|
}
|
|
|
|
/* Second level indents are four spaces. */
|
|
while (cnt < 20)
|
|
z = a + really + long + statment + that + needs +
|
|
two lines + gets + indented + four + spaces + on +
|
|
the + second + and + subsequent + lines.
|
|
|
|
/*
|
|
* Closing and opening braces go on the same line as the else.
|
|
* Don't add braces that aren't necessary.
|
|
*/
|
|
if (test)
|
|
stmt;
|
|
else if (bar) {
|
|
stmt;
|
|
stmt;
|
|
} else
|
|
stmt;
|
|
|
|
/* No spaces after function names. */
|
|
if (error = function(a1, a2))
|
|
exit(error);
|
|
|
|
/*
|
|
* Unary operators don't require spaces, binary operators do.
|
|
* Don't use parenthesis unless they're required for precedence,
|
|
* or the statement is really confusing without them.
|
|
*/
|
|
a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
|
|
k = !(l & FLAGS);
|
|
|
|
/*
|
|
* Exits should be 0 on success, and 1 on failure. Don't
|
|
* denote all the possible exit points, using the integers
|
|
* 1 through 300.
|
|
*/
|
|
exit(0); /* Avoid obvious comments such as "Exit 0 on success." */
|
|
}
|
|
|
|
/*
|
|
* If a function type is declared, it should be on a line
|
|
* by itself preceeding the function.
|
|
*/
|
|
static char *
|
|
function(a1, a2, fl, 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, then in alphabetical order; multiple ones per line
|
|
* are okay. Old style function declarations can go on the same
|
|
* line. ANSI style function declarations should go in the
|
|
* include file "extern.h". If a line overflows reuse the type
|
|
* keyword.
|
|
*
|
|
* DO NOT initialize variables in the declarations.
|
|
*/
|
|
extern u_char one;
|
|
extern char two;
|
|
struct foo three, *four;
|
|
double five;
|
|
int *six, seven, eight();
|
|
char *nine, ten, eleven, twelve, thirteen, fourteen, fifteen;
|
|
char *overflow __P((void));
|
|
void *mymalloc __P((u_int));
|
|
|
|
/*
|
|
* 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
|
|
* of (struct foo *)0 or (struct foo *)NULL. Also, test pointers
|
|
* against NULL, i.e. use:
|
|
*
|
|
* (p = f()) == NULL
|
|
* not:
|
|
* !(p = f())
|
|
*
|
|
* Don't use '!' for tests unless it's a boolean, e.g. use
|
|
* "if (*p == '\e0')", not "if (!*p)".
|
|
*
|
|
* Routines returning void * should not have their return
|
|
* values cast to any pointer type.
|
|
*
|
|
* Use err/warn(3), don't roll your own!
|
|
*/
|
|
if ((four = malloc(sizeof(struct foo))) == NULL)
|
|
err(1, NULL);
|
|
if ((six = (int *)overflow()) == NULL)
|
|
errx(1, "Number overflowed.");
|
|
return (eight);
|
|
}
|
|
|
|
/*
|
|
* Don't use ANSI function declarations unless you absolutely have too,
|
|
* i.e. you're declaring functions with variable numbers of arguments.
|
|
*
|
|
* ANSI function return values and braces look like regular functions.
|
|
*/
|
|
int
|
|
function(int a1, int a2)
|
|
{
|
|
...
|
|
}
|
|
|
|
/* Variable numbers of arguments should look like this. */
|
|
#if __STDC__
|
|
#include <stdarg.h>
|
|
#else
|
|
#include <varargs.h>
|
|
#endif
|
|
|
|
void
|
|
#if __STDC__
|
|
vaf(const char *fmt, ...)
|
|
#else
|
|
vaf(fmt, va_alist)
|
|
char *fmt;
|
|
va_dcl
|
|
#endif
|
|
{
|
|
va_list ap;
|
|
#if __STDC__
|
|
va_start(ap, fmt);
|
|
#else
|
|
va_start(ap);
|
|
#endif
|
|
STUFF;
|
|
|
|
va_end(ap); /* No return needed for void functions. */
|
|
}
|
|
|
|
static void
|
|
usage()
|
|
{ /* Insert an empty line if the function has no local variables. */
|
|
|
|
/*
|
|
* Use printf(3), not fputs/puts/putchar/whatever, it's faster
|
|
* and usually cleaner, not to mention avoiding stupid bugs.
|
|
*
|
|
* Usage statements should look like the manual pages. Options
|
|
* w/o operands come first, in alphabetical order inside a single
|
|
* set of braces. Followed by options with operands, in
|
|
* alphabetical order, each in braces. Followed by required
|
|
* arguments in the order they are specified, followed by optional
|
|
* arguments in the order they are specified. A bar ('|')
|
|
* separates either/or options/arguments, and multiple options/
|
|
* arguments which are specified together are placed in a single
|
|
* set of braces.
|
|
*
|
|
* "usage: f [-ade] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
|
|
* "usage: f [-a | -b] [-c [-de] [-n number]]\en"
|
|
*/
|
|
(void)fprintf(stderr, "usage: f [-ab]\en");
|
|
exit(1);
|
|
}
|
|
.Ed
|
|
.Sh HISTORY
|
|
This man page is largely based on the src/admin/style/style file from
|
|
the BSD 4.4-Lite2 release, with a few updates to reflect the current
|
|
practice and desire of the FreeBSD project.
|
|
|
|
|