File:  [DragonFly] / src / share / man / man9 / style.9
Revision 1.6: download - view: text, annotated - select for diffs
Wed Feb 25 17:35:29 2004 UTC (10 years, 7 months ago) by joerg
Branches: MAIN
CVS tags: HEAD
Don't use parameter names for kernel prototyps

    1: .\" Copyright (c) 1995-2001 FreeBSD Inc.
    2: .\" All rights reserved.
    3: .\"
    4: .\" Redistribution and use in source and binary forms, with or without
    5: .\" modification, are permitted provided that the following conditions
    6: .\" are met:
    7: .\" 1. Redistributions of source code must retain the above copyright
    8: .\"    notice, this list of conditions and the following disclaimer.
    9: .\" 2. Redistributions in binary form must reproduce the above copyright
   10: .\"    notice, this list of conditions and the following disclaimer in the
   11: .\"    documentation and/or other materials provided with the distribution.
   12: .\"
   13: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
   14: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   15: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   16: .\" ARE DISCLAIMED.  IN NO EVENT SHALL [your name] OR CONTRIBUTORS BE LIABLE
   17: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   18: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
   19: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   20: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   21: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   22: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   23: .\" SUCH DAMAGE.
   24: .\"
   25: .\"
   26: .Dd December 7, 2001
   27: .Dt STYLE 9
   28: .Os
   29: .Sh NAME
   30: .Nm style
   31: .Nd "kernel source file style guide"
   32: .Sh DESCRIPTION
   33: This file specifies the preferred style for kernel source files in the
   34: .Fx
   35: source tree.
   36: It is also a guide for preferred userland code style.
   37: Many of the style rules are implicit in the examples.
   38: Be careful to check the examples before assuming that
   39: .Nm
   40: is silent on an issue.
   41: .Bd -literal
   42: /*
   43:  * Style guide for DragonFly.  Based on the CSRG's KNF (Kernel Normal Form).
   44:  *
   45:  *	@(#)style	1.14 (Berkeley) 4/28/95
   46:  * $FreeBSD: src/share/man/man9/style.9,v 1.32.2.19 2002/04/14 19:28:03 asmodai Exp $
   47:  * $DragonFly: src/share/man/man9/style.9,v 1.6 2004/02/25 17:35:29 joerg Exp $
   48:  */
   49: 
   50: /*
   51:  * VERY important single-line comments look like this.
   52:  */
   53: 
   54: /* Most single-line comments look like this. */
   55: 
   56: /*
   57:  * Multi-line comments look like this.  Make them real sentences.  Fill
   58:  * them so they look like real paragraphs.
   59:  */
   60: 
   61: /*
   62:  * XXX in a comment indicates code which is incomplete, suboptimal,
   63:  * or otherwise deserving of further attention.
   64:  */
   65: 
   66: .Ed
   67: .Pp
   68: Version control system ID tags should only exist once in a file
   69: (unlike this one).
   70: All VCS (version control system) revision identification from files obtained
   71: from elsewhere should be maintained in comments, including, where applicable,
   72: multiple IDs showing a file's history.
   73: In general, keep the IDs intact, including any
   74: .So Li $ Sc Ns s .
   75: There is no reason to add
   76: .Qq Li "From"
   77: in front of foreign VCS IDs.
   78: All VCS IDs should generally be placed in comments somewhere near the
   79: top of the source, typically either before or after the copyright message.
   80: .Pp
   81: Leave another blank line before the header files.
   82: .Pp
   83: Kernel include files (i.e.\&
   84: .Pa sys/*.h )
   85: come first; normally, include
   86: .Aq Pa sys/types.h
   87: OR
   88: .Aq Pa sys/param.h ,
   89: but not both.
   90: .Aq Pa sys/types.h
   91: includes
   92: .Aq Pa sys/cdefs.h ,
   93: and it is okay to depend on that.
   94: .Bd -literal
   95: #include <sys/types.h>	/* Non-local includes in angle brackets. */
   96: .Ed
   97: .Pp
   98: For a network program, put the network include files next.
   99: .Bd -literal
  100: #include <net/if.h>
  101: #include <net/if_dl.h>
  102: #include <net/route.h>
  103: #include <netinet/in.h>
  104: #include <protocols/rwhod.h>
  105: .Ed
  106: .Pp
  107: Do not use files in
  108: .Pa /usr/include
  109: for files in the kernel.
  110: .Pp
  111: Leave a blank line before the next group, the
  112: .Pa /usr
  113: include files,
  114: which should be sorted alphabetically by name.
  115: .Bd -literal
  116: #include <stdio.h>
  117: .Ed
  118: .Pp
  119: Global pathnames are defined in
  120: .Aq Pa paths.h .
  121: Pathnames local
  122: to the program go in
  123: .Qq Pa pathnames.h
  124: in the local directory.
  125: .Bd -literal
  126: #include <paths.h>
  127: .Ed
  128: .Pp
  129: Leave another blank line before the user include files.
  130: .Bd -literal
  131: #include "pathnames.h"		/* Local includes in double quotes. */
  132: .Ed
  133: .Pp
  134: Do not
  135: .Ic #define
  136: or declare names in the implementation namespace except
  137: for implementing application interfaces.
  138: .Pp
  139: The names of
  140: .Dq unsafe
  141: macros (ones that have side effects), and the names of macros for
  142: manifest constants, are all in uppercase.
  143: The expansions of expression-like macros are either a single token
  144: or have outer parentheses.
  145: Put a single tab character between the
  146: .Ic #define
  147: and the macro name.
  148: If a macro is an inline expansion of a function, the function name is
  149: all in lowercase and the macro has the same name all in uppercase.
  150: .\" XXX the above conflicts with ANSI style where the names are the
  151: .\" same and you #undef the macro (if any) to get the function.
  152: .\" It is not followed for MALLOC(), and not very common if inline
  153: .\" functions are used.
  154: If a
  155: macro needs more than a single line, use braces
  156: .Ql ( \&{
  157: and
  158: .Ql \&} ) .
  159: Right-justify the
  160: backslashes; it makes it easier to read.
  161: If the macro encapsulates a compound statement, enclose it in a
  162: .Ic do
  163: loop,
  164: so that it can safely be used in
  165: .Ic if
  166: statements.
  167: Any final statement-terminating semicolon should be
  168: supplied by the macro invocation rather than the macro, to make parsing easier
  169: for pretty-printers and editors.
  170: .Bd -literal
  171: #define	MACRO(x, y) do {						\e
  172: 	variable = (x) + (y);						\e
  173: 	(y) += 2;							\e
  174: } while(0)
  175: .Ed
  176: .Pp
  177: Enumeration values are all uppercase.
  178: .Bd -literal
  179: enum enumtype { ONE, TWO } et;
  180: .Ed
  181: .Pp
  182: When declaring variables in structures, declare them sorted by use, then
  183: by size, and then in alphabetical order.
  184: The first category normally does not apply, but there are exceptions.
  185: Each one gets its own line.
  186: Try to make the structure
  187: readable by aligning the member names using either one or two tabs
  188: depending upon your judgment.
  189: You should use one tab if it suffices to align most of the member names.
  190: Names following extremely long types
  191: should be separated by a single space.
  192: .Pp
  193: Major structures should be declared at the top of the file in which they
  194: are used, or in separate header files if they are used in multiple
  195: source files.
  196: Use of the structures should be by separate declarations
  197: and should be
  198: .Ic extern
  199: if they are declared in a header file.
  200: .Bd -literal
  201: struct foo {
  202: 	struct foo	*next;		/* List of active foo. */
  203: 	struct mumble	amumble;	/* Comment for mumble. */
  204: 	int		bar;		/* Try to align the comments. */
  205: 	struct verylongtypename *baz;	/* Won't fit in 2 tabs. */
  206: };
  207: struct foo *foohead;			/* Head of global foo list. */
  208: .Ed
  209: .Pp
  210: Use
  211: .Xr queue 3
  212: macros rather than rolling your own lists, whenever possible.
  213: Thus,
  214: the previous example would be better written:
  215: .Bd -literal
  216: #include <sys/queue.h>
  217: 
  218: struct foo {
  219: 	LIST_ENTRY(foo)	link;		/* Use queue macros for foo lists. */
  220: 	struct mumble	amumble;	/* Comment for mumble. */
  221: 	int		bar;		/* Try to align the comments. */
  222: 	struct verylongtypename *baz;	/* Won't fit in 2 tabs. */
  223: };
  224: LIST_HEAD(, foo) foohead;		/* Head of global foo list. */
  225: .Ed
  226: .Pp
  227: Avoid using typedefs for structure types.
  228: This makes it impossible
  229: for applications to use pointers to such a structure opaquely, which
  230: is both possible and beneficial when using an ordinary struct tag.
  231: When convention requires a
  232: .Ic typedef ,
  233: make its name match the struct tag.
  234: Avoid typedefs ending in
  235: .Dq Li _t ,
  236: except as specified in Standard C or by \*[Px].
  237: .Bd -literal
  238: /* Make the structure name match the typedef. */
  239: typedef struct bar {
  240: 	int	level;
  241: } BAR;
  242: typedef	int		foo;		/* This is foo. */
  243: typedef	const long	baz;		/* This is baz. */
  244: .Ed
  245: .Pp
  246: All functions are prototyped somewhere.
  247: .Pp
  248: Function prototypes for private functions (i.e. functions not used
  249: elsewhere) go at the top of the first source module.
  250: Functions
  251: local to one source module should be declared
  252: .Ic static .
  253: .Pp
  254: Functions used from other parts of the kernel are prototyped in the
  255: relevant include file.
  256: .Pp
  257: Functions that are used locally in more than one module go into a
  258: separate header file, e.g.\&
  259: .Qq Pa extern.h .
  260: .Pp
  261: Avoid using the
  262: .Dv __P
  263: macro from the include file
  264: .Aq Pa sys/cdefs.h .
  265: Code in the DragonFly source tree is not
  266: expected to be K&R compliant.
  267: .Pp
  268: Changes to existing files should be consistent with that file's conventions.
  269: In general, code can be considered
  270: .Dq "new code"
  271: when it makes up about 50% or more of the file(s) involved.
  272: This is enough
  273: to break precedents in the existing code and use the current
  274: .Nm
  275: guidelines.
  276: .Pp
  277: Function prototypes for the kernel have parameter names associated
  278: with parameter types. E.g., in the kernel use:
  279: .Bd -literal
  280: void	function(int fd);
  281: .Ed
  282: .Pp
  283: Prototypes that are visible to userland applications
  284: should not include parameter names with the types, to avoid
  285: possible collisions with defined macro names.
  286: I.e., use:
  287: .Bd -literal
  288: void	function(int);
  289: .Ed
  290: .Pp
  291: Prototypes may have an extra space after a tab to enable function names
  292: to line up:
  293: .Bd -literal
  294: static char	*function(int _arg, const char *_arg2, struct foo *_arg3,
  295: 		    struct bar *_arg4);
  296: static void	 usage(void);
  297: 
  298: /*
  299:  * All major routines should have a comment briefly describing what
  300:  * they do.  The comment before the "main" routine should describe
  301:  * what the program does.
  302:  */
  303: int
  304: main(int argc, char *argv[])
  305: {
  306: 	long num;
  307: 	int ch;
  308: 	char *ep;
  309: 
  310: .Ed
  311: .Pp
  312: For consistency,
  313: .Xr getopt 3
  314: should be used to parse options.
  315: Options
  316: should be sorted in the
  317: .Xr getopt 3
  318: call and the
  319: .Ic switch
  320: statement, unless
  321: parts of the
  322: .Ic switch
  323: cascade.
  324: Elements in a
  325: .Ic switch
  326: statement that cascade should have a
  327: .Li FALLTHROUGH
  328: comment.
  329: Numerical arguments should be checked for accuracy.
  330: Code that cannot be reached should have a
  331: .Li NOTREACHED
  332: comment.
  333: .Bd -literal
  334: 	while ((ch = getopt(argc, argv, "abn:")) != -1)
  335: 		switch (ch) {		/* Indent the switch. */
  336: 		case 'a':		/* Don't indent the case. */
  337: 			aflag = 1;
  338: 			/* FALLTHROUGH */
  339: 		case 'b':
  340: 			bflag = 1;
  341: 			break;
  342: 		case 'n':
  343: 			num = strtol(optarg, &ep, 10);
  344: 			if (num <= 0 || *ep != '\e0') {
  345: 				warnx("illegal number, -n argument -- %s",
  346: 				    optarg);
  347: 				usage();
  348: 			}
  349: 			break;
  350: 		case '?':
  351: 		default:
  352: 			usage();
  353: 			/* NOTREACHED */
  354: 		}
  355: 	argc -= optind;
  356: 	argv += optind;
  357: .Ed
  358: .Pp
  359: Space after keywords
  360: .Pq Ic if , while , for , return , switch .
  361: No braces are
  362: used for control statements with zero or only a single statement unless that
  363: statement is more than a single line in which case they are permitted.
  364: Forever loops are done with
  365: .Ic for Ns 's ,
  366: not
  367: .Ic while Ns 's .
  368: .Bd -literal
  369: 	for (p = buf; *p != '\e0'; ++p)
  370: 		;	/* nothing */
  371: 	for (;;)
  372: 		stmt;
  373: 	for (;;) {
  374: 		z = a + really + long + statement + that + needs +
  375: 		    two lines + gets + indented + four + spaces +
  376: 		    on + the + second + and + subsequent + lines;
  377: 	}
  378: 	for (;;) {
  379: 		if (cond)
  380: 			stmt;
  381: 	}
  382: 	if (val != NULL)
  383: 		val = realloc(val, newsize);
  384: .Ed
  385: .Pp
  386: Parts of a
  387: .Ic for
  388: loop may be left empty.
  389: Do not put declarations
  390: inside blocks unless the routine is unusually complicated.
  391: .Bd -literal
  392: 	for (; cnt < 15; cnt++) {
  393: 		stmt1;
  394: 		stmt2;
  395: 	}
  396: .Ed
  397: .Pp
  398: Indentation used for program block structure is an 8 character tab.
  399: Second level indents used for line continuation are four spaces.
  400: If you have to wrap a long statement, put the operator at the end of the
  401: line.
  402: .Bd -literal
  403: 	while (cnt < 20 && this_variable_name_is_really_far_too_long &&
  404: 	    ep != NULL)
  405: 		z = a + really + long + statement + that + needs +
  406: 		    two lines + gets + indented + four + spaces +
  407: 		    on + the + second + and + subsequent + lines;
  408: .Ed
  409: .Pp
  410: Do not add whitespace at the end of a line, and only use tabs
  411: followed by spaces
  412: to form the indentation.
  413: Do not use more spaces than a tab will produce
  414: and do not use spaces in front of tabs.
  415: .Pp
  416: Closing and opening braces go on the same line as the
  417: .Ic else .
  418: Braces that are not necessary may be left out.
  419: .Bd -literal
  420: 	if (test)
  421: 		stmt;
  422: 	else if (bar) {
  423: 		stmt;
  424: 		stmt;
  425: 	} else
  426: 		stmt;
  427: .Ed
  428: .Pp
  429: No spaces after function names.
  430: Commas have a space after them.
  431: No spaces
  432: after
  433: .Ql \&(
  434: or
  435: .Ql \&[
  436: or preceding
  437: .Ql \&]
  438: or
  439: .Ql \&)
  440: characters.
  441: .Bd -literal
  442: 	error = function(a1, a2);
  443: 	if (error != 0)
  444: 		exit(error);
  445: .Ed
  446: .Pp
  447: Unary operators do not require spaces, binary operators do.
  448: Do not use parentheses unless they are required for precedence or unless the
  449: statement is confusing without them.
  450: Remember that other people may become
  451: confused more easily than you.
  452: Do YOU understand the following?
  453: .Bd -literal
  454: 	a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
  455: 	k = !(l & FLAGS);
  456: .Ed
  457: .Pp
  458: Exits should be 0 on success, or according to the predefined
  459: values in
  460: .Xr sysexits 3 .
  461: .Bd -literal
  462: 	exit(EX_OK);	/*
  463: 			 * Avoid obvious comments such as
  464: 			 * "Exit 0 on success."
  465: 			 */
  466: }
  467: .Ed
  468: .Pp
  469: The function type should be on a line by itself
  470: preceding the function.
  471: .Bd -literal
  472: static char *
  473: function(int a1, int a2, float fl, int a4)
  474: {
  475: .Ed
  476: .Pp
  477: When declaring variables in functions declare them sorted by size,
  478: then in alphabetical order; multiple ones per line are okay.
  479: If a line overflows reuse the type keyword.
  480: .Pp
  481: Be careful to not obfuscate the code by initializing variables in
  482: the declarations.
  483: Use this feature only thoughtfully.
  484: DO NOT use function calls in initializers.
  485: .Bd -literal
  486: 	struct foo one, *two;
  487: 	double three;
  488: 	int *four, five;
  489: 	char *six, seven, eight, nine, ten, eleven, twelve;
  490: 
  491: 	four = myfunction();
  492: .Ed
  493: .Pp
  494: Do not declare functions inside other functions; ANSI C says that
  495: such declarations have file scope regardless of the nesting of the
  496: declaration.
  497: Hiding file declarations in what appears to be a local
  498: scope is undesirable and will elicit complaints from a good compiler.
  499: .Pp
  500: Casts are not followed by a space.
  501: Note that
  502: .Xr indent 1
  503: does not understand this rule.
  504: .Pp
  505: For the purposes of formatting, treat
  506: .Ic return
  507: and
  508: .Ic sizeof
  509: as functions.  In other words, they are not
  510: followed by a space, and their single argument
  511: should be enclosed in parentheses.
  512: .Pp
  513: .Dv NULL
  514: is the preferred null pointer constant.
  515: Use
  516: .Dv NULL
  517: instead of
  518: .Vt ( "type *" ) Ns 0
  519: or
  520: .Vt ( "type *" ) Ns Dv NULL
  521: in contexts where the compiler knows the
  522: type, e.g., in assignments.
  523: Use
  524: .Vt ( "type *" ) Ns Dv NULL
  525: in other contexts,
  526: in particular for all function args.
  527: (Casting is essential for
  528: variadic args and is necessary for other args if the function prototype
  529: might not be in scope.)
  530: Test pointers against
  531: .Dv NULL ,
  532: e.g., use:
  533: .Pp
  534: .Bd -literal
  535: (p = f()) == NULL
  536: .Ed
  537: .Pp
  538: not:
  539: .Bd -literal
  540: !(p = f())
  541: .Ed
  542: .Pp
  543: Do not use
  544: .Ic \&!
  545: for tests unless it is a boolean, e.g. use
  546: .Bd -literal
  547: if (*p == '\e0')
  548: .Ed
  549: .Pp
  550: not
  551: .Bd -literal
  552: if (!*p)
  553: .Ed
  554: .Pp
  555: Routines returning
  556: .Vt "void *"
  557: should not have their return values cast
  558: to any pointer type.
  559: .Pp
  560: Use
  561: .Xr err 3
  562: or
  563: .Xr warn 3 ,
  564: do not roll your own.
  565: .Bd -literal
  566: 	if ((four = malloc(sizeof(struct foo))) == NULL)
  567: 		err(1, (char *)NULL);
  568: 	if ((six = (int *)overflow()) == NULL)
  569: 		errx(1, "number overflowed");
  570: 	return (eight);
  571: }
  572: .Ed
  573: .Pp
  574: Avoid old-style function declarations that look like this:
  575: .Bd -literal
  576: static char *
  577: function(a1, a2, fl, a4)
  578: 	int a1, a2;	/* Declare ints, too, don't default them. */
  579: 	float fl;	/* Beware double vs. float prototype differences. */
  580: 	int a4;		/* List in order declared. */
  581: {
  582: .Ed
  583: .Pp
  584: Use ANSI function declarations instead.
  585: Long parameter lists are wrapped with a normal four space indent.
  586: .Pp
  587: Variable numbers of arguments should look like this.
  588: .Bd -literal
  589: #include <stdarg.h>
  590: 
  591: void
  592: vaf(const char *fmt, ...)
  593: {
  594: 	va_list ap;
  595: 
  596: 	va_start(ap, fmt);
  597: 	STUFF;
  598: 	va_end(ap);
  599: 	/* No return needed for void functions. */
  600: }
  601: 
  602: static void
  603: usage(void)
  604: {
  605: 	/* Insert an empty line if the function has no local variables. */
  606: .Ed
  607: .Pp
  608: Use
  609: .Xr printf 3 ,
  610: not
  611: .Xr fputs 3 ,
  612: .Xr puts 3 ,
  613: .Xr putchar 3 ,
  614: whatever; it is faster and usually cleaner, not
  615: to mention avoiding stupid bugs.
  616: .Pp
  617: Usage statements should look like the manual pages
  618: .Sx SYNOPSIS .
  619: The usage statement should be structured in the following order:
  620: .Bl -enum
  621: .It
  622: Options without operands come first,
  623: in alphabetical order,
  624: inside a single set of brackets
  625: .Ql ( \&[
  626: and
  627: .Ql \&] ) .
  628: .It
  629: Options with operands come next,
  630: also in alphabetical order,
  631: with each option and its argument inside its own pair of brackets.
  632: .It
  633: Required arguments
  634: (if any)
  635: are next,
  636: listed in the order they should be specified on the command line.
  637: .It
  638: Finally,
  639: any optional arguments should be listed,
  640: listed in the order they should be specified,
  641: and all inside brackets.
  642: .El
  643: .Pp
  644: A bar
  645: .Pq Ql \&|
  646: separates
  647: .Dq either-or
  648: options/arguments,
  649: and multiple options/arguments which are specified together are
  650: placed in a single set of brackets.
  651: .Bd -literal -offset 4n
  652: "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
  653: "usage: f [-a | -b] [-c [-dEe] [-n number]]\en"
  654: .Ed
  655: .Bd -literal
  656: 	(void)fprintf(stderr, "usage: f [-ab]\en");
  657: 	exit(EX_USAGE);
  658: }
  659: .Ed
  660: .Pp
  661: Note that the manual page options description should list the options in
  662: pure alphabetical order.
  663: That is, without regard to whether an option takes arguments or not.
  664: The alphabetical ordering should take into account the case ordering
  665: shown above.
  666: .Pp
  667: New core kernel code should be reasonably compliant with the
  668: .Nm
  669: guides.
  670: The guidelines for third-party maintained modules and device drivers are more
  671: relaxed but at a minimum should be internally consistent with their style.
  672: .Pp
  673: Stylistic changes (including whitespace changes) are hard on the source
  674: repository and are to be avoided without good reason.
  675: Code that is approximately
  676: .Fx
  677: KNF
  678: .Nm
  679: compliant in the repository must not diverge from compliance.
  680: .Pp
  681: Whenever possible, code should be run through a code checker
  682: (e.g.,
  683: .Xr lint 1
  684: or
  685: .Nm gcc Fl Wall )
  686: and produce minimal warnings.
  687: .Sh SEE ALSO
  688: .Xr indent 1 ,
  689: .Xr lint 1 ,
  690: .Xr err 3 ,
  691: .Xr sysexits 3 ,
  692: .Xr warn 3
  693: .Sh HISTORY
  694: This man page is largely based on the
  695: .Pa src/admin/style/style
  696: file from the
  697: .Bx 4.4 Lite2
  698: release, with occasional updates to reflect the current practice and
  699: desire of the
  700: .Fx
  701: project.