1 .\" Copyright (c) 1995-2001 FreeBSD Inc.
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" Style guide for DragonFly. Based on the CSRG's KNF (Kernel Normal Form).
27 .\" @(#)style 1.14 (Berkeley) 4/28/95
28 .\" $FreeBSD: src/share/man/man9/style.9,v 1.32.2.19 2002/04/14 19:28:03 asmodai Exp $
35 .Nd "kernel source file style guide"
37 This file specifies the preferred style for kernel source files in the
40 It is also a guide for preferred userland code style.
41 Many of the style rules are implicit in the examples.
42 Be careful to check the examples before assuming that
44 is silent on an issue.
47 * VERY important single-line comments look like this.
50 /* Most single-line comments look like this. */
53 * Multi-line comments look like this. Make them real sentences. Fill
54 * them so they look like real paragraphs.
58 * XXX in a comment indicates code which is incomplete, suboptimal,
59 * or otherwise deserving of further attention.
64 Version control system ID tags should only exist once in a file
66 All VCS (version control system) revision identification from files obtained
67 from elsewhere should be maintained in comments, including, where applicable,
68 multiple IDs showing a file's history.
69 In general, keep the IDs intact, including any
71 There is no reason to add
73 in front of foreign VCS IDs.
74 All VCS IDs should generally be placed in comments somewhere near the
75 top of the source, typically either before or after the copyright message.
77 Leave another blank line before the header files.
79 Kernel include files (i.e.\&
81 come first; normally, include
89 and it is okay to depend on that.
91 #include <sys/types.h> /* Non-local includes in angle brackets. */
94 For a network program, put the network include files next.
97 #include <net/if_dl.h>
98 #include <net/route.h>
99 #include <netinet/in.h>
100 #include <protocols/rwhod.h>
105 for files in the kernel.
107 Leave a blank line before the next group, the
110 which should be sorted alphabetically by name.
115 Global pathnames are defined in
120 in the local directory.
125 Leave another blank line before the user include files.
127 #include "pathnames.h" /* Local includes in double quotes. */
132 or declare names in the implementation namespace except
133 for implementing application interfaces.
137 macros (ones that have side effects), and the names of macros for
138 manifest constants, are all in uppercase.
139 The expansions of expression-like macros are either a single token
140 or have outer parentheses.
141 Put a single tab character between the
144 If a macro is an inline expansion of a function, the function name is
145 all in lowercase and the macro has the same name all in uppercase.
146 .\" XXX the above conflicts with ANSI style where the names are the
147 .\" same and you #undef the macro (if any) to get the function.
148 .\" It is not followed for MALLOC(), and not very common if inline
149 .\" functions are used.
151 macro needs more than a single line, use braces
156 backslashes; it makes it easier to read.
157 If the macro encapsulates a compound statement, enclose it in a
160 so that it can safely be used in
163 Any final statement-terminating semicolon should be
164 supplied by the macro invocation rather than the macro, to make parsing easier
165 for pretty-printers and editors.
167 #define MACRO(x, y) do { \e
168 variable = (x) + (y); \e
173 Enumeration values are all uppercase.
175 enum enumtype { ONE, TWO } et;
178 As fixed size integers the
180 defined types are preferred:
181 .Bd -literal -offset indent
182 uint8_t 8 bits fixed size unsigned integer
183 uint16_t 16 bits fixed size unsigned integer
184 uint32_t 32 bits fixed size unsigned integer
185 uint64_t 64 bits fixed size unsigned integer
188 When declaring variables in structures, declare them sorted by use, then
189 by size, and then in alphabetical order.
190 The first category normally does not apply, but there are exceptions.
191 Each one gets its own line.
192 Try to make the structure
193 readable by aligning the member names using either one or two tabs
194 depending upon your judgment.
195 You should use one tab if it suffices to align most of the member names.
196 Names following extremely long types
197 should be separated by a single space.
199 Major structures should be declared at the top of the file in which they
200 are used, or in separate header files if they are used in multiple
202 Use of the structures should be by separate declarations
205 if they are declared in a header file.
208 struct foo *next; /* List of active foo. */
209 struct mumble amumble; /* Comment for mumble. */
210 int bar; /* Try to align the comments. */
211 struct verylongtypename *baz; /* Won't fit in 2 tabs. */
213 struct foo *foohead; /* Head of global foo list. */
218 macros rather than rolling your own lists, whenever possible.
220 the previous example would be better written:
222 #include <sys/queue.h>
225 LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */
226 struct mumble amumble; /* Comment for mumble. */
227 int bar; /* Try to align the comments. */
228 struct verylongtypename *baz; /* Won't fit in 2 tabs. */
230 LIST_HEAD(, foo) foohead; /* Head of global foo list. */
233 Avoid using typedefs for structure types.
234 This makes it impossible
235 for applications to use pointers to such a structure opaquely, which
236 is both possible and beneficial when using an ordinary struct tag.
237 When convention requires a
239 make its name match the struct tag.
240 Avoid typedefs ending in
242 except as specified in Standard C or by
245 /* Make the structure name match the typedef. */
249 typedef int foo; /* This is foo. */
250 typedef const long baz; /* This is baz. */
253 All functions are prototyped somewhere.
255 Function prototypes for private functions (i.e. functions not used
256 elsewhere) go at the top of the first source module.
258 local to one source module should be declared
261 Functions used from other parts of the kernel are prototyped in the
262 relevant include file.
264 Functions that are used locally in more than one module go into a
265 separate header file, e.g.\&
272 macro from the include file
276 source tree is not expected to be K&R compliant.
278 Changes to existing files should be consistent with that file's conventions.
279 In general, code can be considered
281 when it makes up about 50% or more of the file(s) involved.
283 to break precedents in the existing code and use the current
287 Function prototypes for the kernel have parameter names associated
288 with parameter types. E.g., in the kernel use:
290 void function(int fd);
293 Prototypes that are visible to userland applications
294 should not include parameter names with the types, to avoid
295 possible collisions with defined macro names.
301 Prototypes may have an extra space after a tab to enable function names
304 static char *function(int, const char *, struct foo *, struct bar *,
306 static void usage(void);
309 * All major routines should have a comment briefly describing what
310 * they do. The comment before the "main" routine should describe
311 * what the program does.
314 main(int argc, char **argv)
324 should be used to parse options.
326 should be sorted in the
336 statement that cascade should have a
338 comment, unless they contain no code of their own.
339 Numerical arguments should be checked for accuracy.
340 Code that cannot be reached should have a
344 while ((ch = getopt(argc, argv, "abn:")) != -1)
345 switch (ch) { /* Indent the switch. */
346 case 'a': /* Don't indent the case. */
353 num = strtol(optarg, &ep, 10);
354 if (num <= 0 || *ep != '\e0') {
355 warnx("illegal number, -n argument -- %s",
368 Put a single space after control statement keywords
369 .Pq Ic if , do , while , for , switch .
371 used for control statements with zero or only a single statement unless that
372 statement is more than a single line in which case they are permitted.
374 loops (loops with no test expression, which are only terminated by a
379 inside the loop body) are done with
384 for (p = buf; *p != '\e0'; ++p)
389 z = a + really + long + statement + that + needs +
390 two + lines + gets + indented + four + spaces +
391 on + the + second + and + subsequent + lines;
398 val = realloc(val, newsize);
403 loop may be left empty.
404 Do not put declarations
405 inside blocks unless the routine is unusually complicated.
407 for (; cnt < 15; cnt++) {
413 Indentation used for program block structure is an 8 character tab.
414 Second level indents used for line continuation are four spaces.
415 If you have to wrap a long statement, put the operator at the end of the
418 while (cnt < 20 && this_variable_name_is_really_far_too_long &&
420 z = a + really + long + statement + that + needs +
421 two + lines + gets + indented + four + spaces +
422 on + the + second + and + subsequent + lines;
426 Do not add whitespace at the end of a line, and only use tabs
428 to form the indentation.
429 Do not use more spaces than a tab will produce
430 and do not use spaces in front of tabs.
432 Closing and opening braces go on the same line as the
434 Braces that are not necessary may be left out, but always use braces around
435 complex or confusing sequences, for example if any part of a conditional is
436 multi-line, use braces for all parts of the conditional, and use braces
437 around multi-line substatements of loops or conditionals even if they are
438 theoretically one statement from the compiler's point of view.
456 /* THIS IS WRONG, BRACES SHOULD BE USED */
461 /* THIS IS ALSO WRONG, USE BRACES AROUND THE OUTER CONDITIONAL */
467 Do not put spaces after function names,
472 characters, or preceding
479 But do put a space after commas and semicolons if there is
480 further text on the same line.
482 error = function(a1, a2);
487 Unary operators do not require spaces around them,
488 but binary operators (except for
493 Do not use parentheses unless they are required for precedence or unless the
494 statement is confusing without them.
495 Remember that other people may become
496 confused more easily than you.
497 Do YOU understand the following?
499 a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
503 Casts are not followed by a space.
506 does not understand this rule.
507 Also, for the purposes of formatting, treat
511 as functions. In other words, they are not
512 followed by a space, and their single argument
513 should be enclosed in parentheses.
515 Exits should be 0 on success, or according to the predefined
520 * Avoid obvious comments such as
521 * "Exit 0 on success."
526 The function type should be on a line by itself
527 preceding the function.
530 function(int a1, int a2, float fl, int a4)
534 When declaring variables in functions declare them sorted by size,
535 then in alphabetical order; multiple ones per line are okay.
536 If a line overflows reuse the type keyword.
538 Be careful to not obfuscate the code by initializing variables in
540 Use this feature only thoughtfully.
541 DO NOT use function calls in initializers.
543 struct foo one, *two;
546 char *six, seven, eight, nine, ten, eleven, twelve;
551 Do not declare functions inside other functions; ANSI C says that
552 such declarations have file scope regardless of the nesting of the
554 Hiding file declarations in what appears to be a local
555 scope is undesirable and will elicit complaints from a good compiler.
558 is the preferred null pointer constant.
562 .Vt ( "type *" ) Ns 0
564 .Vt ( "type *" ) Ns Dv NULL
565 in contexts where the compiler knows the
566 type, e.g., in assignments.
568 .Vt ( "type *" ) Ns Dv NULL
570 in particular for all function args.
571 (Casting is essential for
572 variadic args and is necessary for other args if the function prototype
573 might not be in scope.)
574 Test pointers against
588 for tests unless it is a boolean, e.g. use
598 Do not cast the unused return value of a function to (void).
602 should not have their return values cast
609 do not roll your own.
611 if ((four = malloc(sizeof(struct foo))) == NULL)
613 if ((six = (int *)overflow()) == NULL)
614 errx(1, "number overflowed");
619 Avoid old-style function declarations that look like this:
622 function(a1, a2, fl, a4)
623 int a1, a2; /* Declare ints, too, don't default them. */
624 float fl; /* Beware double vs. float prototype differences. */
625 int a4; /* List in order declared. */
629 Use ANSI function declarations instead.
630 Long parameter lists are wrapped so that the first parameter on each line
633 Try to avoid using obsolete functions such as:
642 All new code must avoid using unbounded string functions. For example,
644 should be used instead of
648 should be used instead of
651 Varargs procedures should be formatted as follows:
656 vaf(const char *fmt, ...)
663 /* No return needed for void functions. */
673 whatever; it is faster and usually cleaner, not
674 to mention avoiding stupid bugs.
676 Usage statements should look like the manual pages
678 The usage statement should be structured in the following order:
681 Options without operands come first,
682 in alphabetical order,
683 inside a single set of brackets
688 Options with operands come next,
689 also in alphabetical order,
690 with each option and its argument inside its own pair of brackets.
695 listed in the order they should be specified on the command line.
698 any optional arguments should be listed,
699 listed in the order they should be specified,
700 and all inside brackets.
708 and multiple options/arguments which are specified together are
709 placed in a single set of brackets.
710 .Bd -literal -offset 4n
711 "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
712 "usage: f [-a | -b] [-c [-dEe] [-n number]]\en"
718 fprintf(stderr, "usage: f [-ab]\en");
723 Note that the manual page options description should list the options in
724 pure alphabetical order.
725 That is, without regard to whether an option takes arguments or not.
726 The alphabetical ordering should take into account the case ordering
729 New core kernel code should be reasonably compliant with the
732 The guidelines for third-party maintained modules and device drivers are more
733 relaxed but at a minimum should be internally consistent with their style.
735 Stylistic changes (including whitespace changes) are hard on the source
736 repository and are to be avoided without good reason.
737 Code that is approximately
741 compliant in the repository must not diverge from compliance.
744 default warning options are a reasonable subset and -Werror is enabled for
745 kernel and world, so passing
749 alone is a good check.
750 The warnings of most recent compilers are of high quality.
751 Further analysis can be done using one of the various code checkers such as
762 This man page is largely based on the
763 .Pa src/admin/style/style
766 release, with occasional updates to reflect the current practice and