Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
STYLE(9)		 BSD Kernel Developer's	Manual		      STYLE(9)

NAME
     style -- Kernel source file style guide

DESCRIPTION
     This file specifies the preferred style for kernel	source files in	the
     FreeBSD source tree.  It is also a	guide for preferred user land code
     style.

     /*
      *	Style guide for	the FreeBSD KNF	(Kernel	Normal Form).
      */

     /*
      *	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 (i.e.	sys/*.h) 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 back-
     slashes, it makes it easier to read.  If the macro	encapsulates a com-
     pound statement, enclose it in a "do" loop, so that it can	safely be used
     in	"if" statements.  Any final statement-terminating semicolon should be
     supplied by the macro invocation rather than the macro, to	make parsing
     easier for	pretty-printers	and editors.

     #define MACRO(x, y) do {						     \
	     variable =	(x) + (y);					     \
	     (y) += 2;							     \
     } while(0)

     Enumeration values	are all	uppercase.

     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	*/

     Use queue(3) macros rather	than rolling your own lists, whenever possi-
     ble.  Thus, the previous example would be better written:

     #include <sys/queue.h>
     struct  foo {
	     LIST_ENTRY(foo) link;   /*	Queue macro glue for foo lists */
	     struct  mumble amumble; /*	Comment	for mumble */
	     int     bar;
     };
     LIST_HEAD(, foo) foohead;	     /*	Head of	global foo list	*/

     Avoid using typedefs for structure	types.	This makes it impossible for
     applications to use pointers to such a structure opaquely,	which is both
     possible and beneficial when using	an ordinary struct tag.	 When conven-
     tion requires a typedef, make its name match the struct tag.  Avoid type-
     defs ending in "_t", except as specified in Standard C or by POSIX.

     /*	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	else-
     where) go at the top of the first source module.  Functions local to one
     source module should be declared `static'.

     Functions used from other parts of	the kernel are prototyped in the rele-
     vant include file.

     Functions that are	used locally in	more than one module go	into a sepa-
     rate header file, e.g.  extern.h.

     Only use the __P macro from the include file <sys/cdefs.h>	if the source
     file in general is	(to be)	compilable with	a K&R Old testament compiler.
     Use of the	__P macro in new code is discouraged, although modifications
     to	existing files should be consistent with that file's conventions.

     In	general	code can be considered "new code" when it makes	up about 50%
     or	more of	the file[s] involved.  This is enough to break precedents in
     the existing code and use the current style guidelines.

     The kernel	has a name associated with parameter types, e.g., in the ker-
     nel use:

     void    function(int fd);

     In	header files visible to	user land applications,	prototypes that	are
     visible must use either protected names or	no names with the types.  It
     is	preferable to use protected names.  e.g., use:

     void    function(int);

     or:

     void    function(int _fd);

     Prototypes	may have an extra space	after a	tab to enable function names
     to	line up:

     static char     *function(int _arg, const char *_arg2, struct foo *_arg3,
			       struct bar *_arg4);
     static void      usage(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(int argc, char *argv[])
     {
	     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")) !=	-1)
		     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 != '\0')
				     err("illegal number -- %s", optarg);
			     break;
		     case '?':
		     default:
			     usage();
			     /*	NOTREACHED */
		     }
	     argc -= optind;
	     argv += optind;

     Space after keywords (if, while, for, return, switch).  No	braces are
     used for control statements with zero or only a single statement unless
     that statement is more than a single line in which	case they are permit-
     ted.  Forever loops are done with for's, not while's.

	     for (p = buf; *p != '\0'; ++p)
		     ;	     /*	nothing	*/
	     for (;;)
		     stmt;
	     for (;;) {
		     z = a + really + long + statement + that +	needs +
			 two lines + gets + indented + four + spaces +
			 on + the + second + and + subsequent +	lines;
	     }
	     for (;;) {
		     if	(cond)
			     stmt;
	     }
	     if	(val !=	NULL)
		     val = realloc(val,	newsize);

     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;
	     }

     Indentation is an 8 character tab.	 Second	level indents are four spaces.

	     while (cnt	< 20)
		     z = a + really + long + statement + that +	needs +
			 two lines + gets + indented + four + spaces +
			 on + the + second + and + subsequent +	lines.

     Do	not add	whitespace at the end of a line, and only use tabs then	spaces
     to	form the indentation.  Do not use more spaces than a tab will produce
     and do not	use spaces in front of tabs.

     Closing and opening braces	go on the same line as the else.  Braces that
     aren't necessary may be left out.

	     if	(test)
		     stmt;
	     else if (bar) {
		     stmt;
		     stmt;
	     } else
		     stmt;

     No	spaces after function names.  Commas have a space after	them.  No spa-
     ces after `(' or `[' or preceding `]' or `)' characters.

	     if	(error = function(a1, a2))
		     exit(error);

     Unary operators don't require spaces, binary operators do.	Don't use
     parentheses unless	they're	required for precedence, or the	statement is
     confusing without them. Remember that other people	may confuse easier
     then you. Do YOU understand the following?

	     a = b->c[0] + ~d == (e || f) || g && h ? i	: j >> 1;
	     k = !(l & FLAGS);

     Exits should be 0 on success, or according	to the predefined values in
     sysexits(3).

	     exit(EX_OK);    /*
			      *	Avoid obvious comments such as
			      *	"Exit 0	on success."
			      */
     }

     The function type should be on a line by itself preceding the function.

     static char *
     function(int a1, int a2, float fl,	int a4)
     {

     When declaring variables in functions declare them	sorted by size,	then
     in	alphabetical order; multiple ones per line are okay.  Declaring	func-
     tions inside functions is not recommendable, since	their linkage scope is
     always global.  If	a line overflows reuse the type	keyword.

     Be	careful	to not obfuscate the code by initializing variables in the
     declarations.  Use	this feature only thoughtfully.	 DO NOT	use function
     calls in initializers!

	     struct foo	one, *two;
	     double three;
	     int *four,	five;
	     char *six,	seven, eight, nine, ten, eleven, twelve;

	     four = myfunction();

     Do	not declare functions inside other functions; ANSI C says that such
     declarations have file scope regardless of	the nesting of the declara-
     tion.  Hiding file	declarations in	what appears to	be a local scope is
     undesirable and will elicit complaints from a good	compiler.

     Casts and sizeof's	are not	followed by a space.  Note that	indent(1) does
     not understand this rule.

     NULL is the preferred null	pointer	constant.  Use NULL instead of (type
     *)0 or (type *)NULL in contexts where the compiler	knows the type,	e.g.,
     in	assignments.  Use (type	*)NULL in other	contexts, in particular	for
     all function args.	 (Casting is essential for varadic args	and is neces-
     sary for other args if the	function prototype might not be	in scope.)
     Test pointers against NULL, e.g., use:

     (p	= f()) == NULL

     not:

     !(p = f())

     Don't use '!' for tests unless it's a boolean, e.g. use

     if	(*p == '\0')

     not

     if	(!*p)

     Routines returning	void * should not have their return values cast	to any
     pointer type.

     Use err(3)	or warn(3), don't roll your own!

	     if	((four = malloc(sizeof(struct foo))) ==	NULL)
		     err(1, (char *)NULL);
	     if	((six =	(int *)overflow()) == NULL)
		     errx(1, "Number overflowed.");
	     return (eight);
     }

     Old-style function	declarations look like this:

     static char *
     function(a1, a2, fl, a4)
	     int a1, a2;     /*	Declare	ints, too, don't default them. */
	     float fl;	     /*	Beware double vs. float	prototype differences. */
	     int a4;	     /*	List in	order declared.	*/
     {

     Use ANSI function declarations unless you explicitly need K&R compatabil-
     ity.

     Variable numbers of arguments should look like this.

     #include <stdarg.h>

     void
     vaf(const char *fmt, ...)
     {
	     va_list ap;

	     va_start(ap, fmt);
	     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.  Fol-
     lowed 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 (`|') sepa-
     rates 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]]\n" "us-
	age: f [-a | -b] [-c [-de] [-n number]]\n"

	     (void)fprintf(stderr, "usage: f [-ab]\n");
	     exit(1);
     }

     New core kernel code should be reasonably compliant with the style
     guides.  The guidelines for third-party maintained	modules	and device
     drivers are more relaxed but at a minimum should be internally consistant
     with their	style.

     Stylistic changes (including whitespace changes) are hard on the source
     repository	and are	to be avoided without good reason.  Code that is ap-
     proximately KNF compliant in the repository must not diverge from compli-
     ance.

     Whenever possible,	code should be run through a code checker (e.g., "gcc
     -Wall" or xlint(1)) and produce minimal warnings.

SEE ALSO
     indent(1),	err(3),	sysexits(3), warn(3)

HISTORY
     This man page is largely based on the src/admin/style/style file from the
     BSD 4.4-Lite2 release, with updates to reflect the	current	practice and
     desire of the FreeBSD project.

FreeBSD			       December	14, 1995		       FreeBSD

NAME | DESCRIPTION | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9&manpath=FreeBSD+3.2-RELEASE>

home | help