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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
STYLE(9)	       FreeBSD Kernel Developer's Manual	      STYLE(9)

     style -- kernel source file style guide

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

      *	$FreeBSD: src/share/man/man9/style.9,v 1.105 2003/11/12	10:53:52 fanf Exp $

      *	VERY important single-line comments look like this.


      *	them so	they look like real paragraphs.

     file (unlike in this one).	 Non-C/C++ source files	follow the example
     above, while C/C++	source files follow the	one below.  All	VCS (version
     control system) revision identification in	files obtained from elsewhere
     should be maintained, including, where applicable,	multiple IDs showing a
     file's history.  In general, do not edit foreign IDs or their infrastruc-
     ture.  Unless otherwise wrapped (such as ``#if defined(LIBC_SCCS)''),
     enclose both in ``#if 0 ... #endif'' to hide any uncompilable bits	and to
     keep the IDs out of object	files.	Only add ``From: '' in front of	for-
     eign VCS IDs if the file is renamed.

     #if 0
     #ifndef lint
     static char sccsid[] = "@(#)style	     1.14 (Berkeley) 4/28/95";
     #endif /* not lint	*/

     #include <sys/cdefs.h>

     Leave another blank line before the header	files.



     For 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>


     Leave a blank line	before the next	group, the /usr/include	files, which
     should be sorted alphabetically by	name.

     #include <stdio.h>

     gram go in	"pathnames.h" in the local directory.

     #include <paths.h>

     Leave another blank line before the user include files.


     Do	not #define or declare names in	the implementation namespace except
     for implementing application interfaces.

     The names of ``unsafe'' macros (ones that have side effects), and the
     names of macros for manifest constants, are all in	uppercase.  The	expan-
     sions of expression-like macros are either	a single token or have outer
     parentheses.  Put a single	tab character between the #define and the
     macro name.  If a macro is	an inline expansion of a function, the func-
     tion name is all in lowercase and the macro has the same name all in
     uppercase.	 Right-justify the backslashes;	it makes it easier to read.
     If	the macro encapsulates a compound statement, enclose it	in a do	loop,
     so	that it	can safely be used in if statements.  Any final	statement-ter-
     minating 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)

     When code is conditionally	compiled using #ifdef or #if, a	comment	may be
     added following the matching #endif or #else to permit the	reader to eas-
     ily discern where conditionally compiled code regions end.	 This comment
     should be used only for (subjectively) long regions, regions greater than
     20	lines, or where	a series of nested #ifdef 's may be confusing to the
     reader.  Exceptions may be	made for cases where code is conditionally not
     compiled for the purposes of lint(1), even	though the uncompiled region
     may be small.  The	comment	should be separated from the #endif or #else
     by	a single space.	 For short conditionally compiled regions, a closing
     comment should not	be used.

     The comment for #endif should match the expression	used in	the corre-
     sponding #if or #ifdef.  The comment for #else and	#elif should match the
     inverse of	the expression(s) used in the preceding	#if and/or #elif
     statements.  In the comments, the subexpression ``defined(FOO)'' is
     abbreviated as ``FOO''.  For the purposes of comments, ``#ifndef FOO'' is
     treated as	``#if !defined(FOO)''.

     #ifdef KTRACE
     #include <sys/ktrace.h>

     #ifdef COMPAT_43
     /*	A large	region here, or	other conditional code.	*/
     #else /* !COMPAT_43 */
     /*	Or here. */
     #endif /* COMPAT_43 */

     #ifndef COMPAT_43
     /*	Yet another large region here, or other	conditional code. */
     #else /* COMPAT_43	*/
     /*	Or here. */
     #endif /* !COMPAT_43*/

     The project is slowly moving to use the ISO/IEC 9899:1999 (``ISO C99'')
     unsigned integer identifiers of the form uintXX_t in preference to	the
     older BSD-style integer identifiers of the	form u_intXX_t.	 New code
     should use	the former, and	old code should	be converted to	the new	form
     if	other major work is being done in that area and	there's	no overriding
     reason to prefer the older	BSD-style.  Like white-space commits, care
     should be taken in	making uintXX_t	only commits.

     Enumeration values	are all	uppercase.

     enum enumtype { ONE, TWO }	et;

     In	declarations, do not put any whitespace	between	asterisks and adjacent
     tokens, except for	tokens that are	identifiers related to types.  (These
     identifiers are the names of basic	types, type qualifiers,	and
     typedef-names other than the one being declared.)	Separate these identi-
     fiers from	asterisks using	a single space.

     Try to make the structure readable	by aligning the	member names using
     either one	or two tabs depending upon your	judgment.  You should use one
     tab only if it suffices to	align at least 90% of the member names.	 Names
     following extremely long types should be separated	by a single space.

     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 mumble   amumble;	     /*	Comment	for mumble. */

     ble.  Thus, the previous example would be better written:

     #include <sys/queue.h>

     struct foo	{
	     struct mumble   amumble;	     /*	Comment	for mumble. */

     Avoid using typedefs for structure	types.	Typedefs are problematic
     because they do not properly hide their underlying	type; for example you
     need to know if the typedef is the	structure itself or a pointer to the
     structure.	 In addition they must be declared exactly once, whereas an
     incomplete	structure type can be mentioned	as many	times as necessary.
     Typedefs are difficult to use in stand-alone header files:	the header
     that defines the typedef must be included before the header that uses it,
     or	by the header that uses	it (which causes namespace pollution), or
     there must	be a back-door mechanism for obtaining the typedef.

     When convention requires a	typedef, make its name match the struct	tag.
     Avoid typedefs ending in ``_t'', except as	specified in Standard C	or by

     /*	Make the structure name	match the typedef. */
     typedef struct bar	{
	     int     level;
     } BAR;
     typedef int	     foo;	     /*	This is	foo. */

     All functions are prototyped somewhere.

     source module should be declared static.

     vant include file.	 Function prototypes should be listed in a logical
     order, preferably alphabetical unless there is a compelling reason	to use
     a different ordering.

     rate header file, e.g. "extern.h".

     Do	not use	the __P	macro.

     In	general	code can be considered ``new code'' when it makes up about 50%
     the existing code and use the current style guidelines.

     nel use:

     void    function(int fd);

     In	header files visible to	userland applications, prototypes that are
     visible must use either ``protected'' names (ones beginning with an
     underscore) or no names with the types.  It is preferable to use pro-
     tected names.  E.g., use:

     void    function(int);


     void    function(int _fd);

     to	line up:

			 struct	bar *_arg4);
     static void      usage(void);

      *	All major routines should have a comment briefly describing what
      *	what the program does.
     main(int argc, char *argv[])
	     char *ep;
	     long num;
	     int ch;

     should have a FALLTHROUGH comment.	 Numerical arguments should be checked

			     aflag = 1;
			     /*	FALLTHROUGH */
		     case 'b':
			     bflag = 1;
		     case 'n':
			     num = strtol(optarg, &ep, 10);
		     case '?':
			     /*	NOTREACHED */
	     argc -= optind;
	     argv += optind;

     Space after keywords (if, while, for, return, switch).  No	braces (`{'
     and `}') 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 permitted.  Forever loops	are done with for's, not while's.

		     ;	     /*	nothing	*/
	     for (;;)
	     for (;;) {
			 two + lines + gets + indented + four +	spaces +
			 on + the + second + and + subsequent +	lines;
	     for (;;) {
		     if	(cond)
	     if	(val !=	NULL)
		     val = realloc(val,	newsize);

     blocks unless the routine is unusually complicated.

	     for (; cnt	< 15; cnt++) {


	     while (cnt	< 20 &&	this_variable_name_is_too_long &&
		 ep != NULL)
			 two + lines + gets + indented + four +	spaces +
			 on + the + second + and + subsequent +	lines;

     produce and do not	use spaces in front of tabs.

     are not necessary may be left out.

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


	     error = function(a1, a2);
	     if	(error != 0)

     parentheses unless	they are required for precedence or unless the state-
     ment is confusing without them.  Remember that other people may confuse
     easier than you.  Do YOU understand the following?

	     k = !(l & FLAGS);


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

     The opening brace of the function body should be on a line	by itself.

     static char *

     When declaring variables in functions declare them	sorted by size,	then
     flows 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;

	     four = myfunction();

     declarations have file scope regardless of	the nesting of the declara-
     undesirable and will elicit complaints from a good	compiler.

     not understand this rule.	sizeof's are written with parenthesis always.
     The redundant parenthesis rules do	not apply to sizeof(var) instances.

     Test pointers against NULL, e.g., use:

     (p	= f()) == NULL


     !(p = f())


     if	(*p == '\0')


     if	(!*p)

     pointer type.

     Values in return statements should	be enclosed in parentheses.


		     err(1, (char *)NULL);
		     errx(1, "number overflowed");
	     return (eight);

     Old-style function	declarations look like this:

     static char *
     function(a1, a2, fl, a4)
	     int a4;	     /*	List in	order declared.	*/


     Variable numbers of arguments should look like this.

     #include <stdarg.h>

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

	     va_start(ap, fmt);
	     /*	No return needed for void functions. */

     static void

     and usually cleaner, not to mention avoiding stupid bugs.

     Usage statements should look like the manual pages	SYNOPSIS.  The usage
     statement should be structured in the following order:


	  each option and its argument inside its own pair of brackets.

	  should be specified on the command line.

	  order	they should be specified, and all inside brackets.

     A bar (`|') separates ``either-or'' options/arguments, and	multiple
     options/arguments which are specified together are	placed in a single set
     of	brackets.



     Note that the manual page options description should list the options in
     takes arguments or	not.  The alphabetical ordering	should take into
     account the case ordering shown above.

     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 consistent
     with their	style.

     Stylistic changes (including whitespace changes) are hard on the source
     approximately FreeBSD KNF style compliant in the repository must not
     diverge from compliance.


     indent(1),	lint(1), err(3), sysexits(3), warn(3), style.Makefile(5)

     4.4BSD-Lite2 release, with	occasional updates to reflect the current
     practice and desire of the	FreeBSD	project.

FreeBSD	10.2		       December	7, 2001			  FreeBSD 10.2


Want to link to this manual page? Use this URL:

home | help