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
31 .Nd "kernel source file style guide"
33 This file specifies the preferred style for kernel source files in the
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
40 is silent on an issue.
43 * Style guide for DragonFly. Based on the CSRG's KNF (Kernel Normal Form).
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.21 2008/05/02 02:05:06 swildner Exp $
51 * VERY important single-line comments look like this.
54 /* Most single-line comments look like this. */
57 * Multi-line comments look like this. Make them real sentences. Fill
58 * them so they look like real paragraphs.
62 * XXX in a comment indicates code which is incomplete, suboptimal,
63 * or otherwise deserving of further attention.
68 Version control system ID tags should only exist once in a file
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
75 There is no reason to add
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.
81 Leave another blank line before the header files.
83 Kernel include files (i.e.\&
85 come first; normally, include
93 and it is okay to depend on that.
95 #include <sys/types.h> /* Non-local includes in angle brackets. */
98 For a network program, put the network include files next.
101 #include <net/if_dl.h>
102 #include <net/route.h>
103 #include <netinet/in.h>
104 #include <protocols/rwhod.h>
109 for files in the kernel.
111 Leave a blank line before the next group, the
114 which should be sorted alphabetically by name.
119 Global pathnames are defined in
124 in the local directory.
129 Leave another blank line before the user include files.
131 #include "pathnames.h" /* Local includes in double quotes. */
136 or declare names in the implementation namespace except
137 for implementing application interfaces.
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
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.
155 macro needs more than a single line, use braces
160 backslashes; it makes it easier to read.
161 If the macro encapsulates a compound statement, enclose it in a
164 so that it can safely be used in
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.
171 #define MACRO(x, y) do { \e
172 variable = (x) + (y); \e
177 Enumeration values are all uppercase.
179 enum enumtype { ONE, TWO } et;
182 As fixed size integers the
184 defined types are preferred:
185 .Bd -literal -offset indent
186 uint8_t 8 bits fixed size unsigned integer
187 uint16_t 16 bits fixed size unsigned integer
188 uint32_t 32 bits fixed size unsigned integer
189 uint64_t 64 bits fixed size unsigned integer
192 When declaring variables in structures, declare them sorted by use, then
193 by size, and then in alphabetical order.
194 The first category normally does not apply, but there are exceptions.
195 Each one gets its own line.
196 Try to make the structure
197 readable by aligning the member names using either one or two tabs
198 depending upon your judgment.
199 You should use one tab if it suffices to align most of the member names.
200 Names following extremely long types
201 should be separated by a single space.
203 Major structures should be declared at the top of the file in which they
204 are used, or in separate header files if they are used in multiple
206 Use of the structures should be by separate declarations
209 if they are declared in a header file.
212 struct foo *next; /* List of active foo. */
213 struct mumble amumble; /* Comment for mumble. */
214 int bar; /* Try to align the comments. */
215 struct verylongtypename *baz; /* Won't fit in 2 tabs. */
217 struct foo *foohead; /* Head of global foo list. */
222 macros rather than rolling your own lists, whenever possible.
224 the previous example would be better written:
226 #include <sys/queue.h>
229 LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */
230 struct mumble amumble; /* Comment for mumble. */
231 int bar; /* Try to align the comments. */
232 struct verylongtypename *baz; /* Won't fit in 2 tabs. */
234 LIST_HEAD(, foo) foohead; /* Head of global foo list. */
237 Avoid using typedefs for structure types.
238 This makes it impossible
239 for applications to use pointers to such a structure opaquely, which
240 is both possible and beneficial when using an ordinary struct tag.
241 When convention requires a
243 make its name match the struct tag.
244 Avoid typedefs ending in
246 except as specified in Standard C or by
249 /* Make the structure name match the typedef. */
253 typedef int foo; /* This is foo. */
254 typedef const long baz; /* This is baz. */
257 All functions are prototyped somewhere.
259 Function prototypes for private functions (i.e. functions not used
260 elsewhere) go at the top of the first source module.
262 local to one source module should be declared
265 Functions used from other parts of the kernel are prototyped in the
266 relevant include file.
268 Functions that are used locally in more than one module go into a
269 separate header file, e.g.\&
276 macro from the include file
280 source tree is not expected to be K&R compliant.
282 Changes to existing files should be consistent with that file's conventions.
283 In general, code can be considered
285 when it makes up about 50% or more of the file(s) involved.
287 to break precedents in the existing code and use the current
291 Function prototypes for the kernel have parameter names associated
292 with parameter types. E.g., in the kernel use:
294 void function(int fd);
297 Prototypes that are visible to userland applications
298 should not include parameter names with the types, to avoid
299 possible collisions with defined macro names.
305 Prototypes may have an extra space after a tab to enable function names
308 static char *function(int, const char *, struct foo *, struct bar *,
310 static void usage(void);
313 * All major routines should have a comment briefly describing what
314 * they do. The comment before the "main" routine should describe
315 * what the program does.
318 main(int argc, char **argv)
328 should be used to parse options.
330 should be sorted in the
340 statement that cascade should have a
342 comment, unless they contain no code of their own, as in the
344 element in the example below.
345 Numerical arguments should be checked for accuracy.
346 Code that cannot be reached should have a
350 while ((ch = getopt(argc, argv, "abn:")) != -1)
351 switch (ch) { /* Indent the switch. */
352 case 'a': /* Don't indent the case. */
359 num = strtol(optarg, &ep, 10);
360 if (num <= 0 || *ep != '\e0') {
361 warnx("illegal number, -n argument -- %s",
375 Put a single space after control statement keywords
376 .Pq Ic if , do , while , for , switch .
378 used for control statements with zero or only a single statement unless that
379 statement is more than a single line in which case they are permitted.
381 loops (loops with no test expression, which are only terminated by a
386 inside the loop body) are done with
391 for (p = buf; *p != '\e0'; ++p)
396 z = a + really + long + statement + that + needs +
397 two + lines + gets + indented + four + spaces +
398 on + the + second + and + subsequent + lines;
405 val = realloc(val, newsize);
410 loop may be left empty.
411 Do not put declarations
412 inside blocks unless the routine is unusually complicated.
414 for (; cnt < 15; cnt++) {
420 Indentation used for program block structure is an 8 character tab.
421 Second level indents used for line continuation are four spaces.
422 If you have to wrap a long statement, put the operator at the end of the
425 while (cnt < 20 && this_variable_name_is_really_far_too_long &&
427 z = a + really + long + statement + that + needs +
428 two + lines + gets + indented + four + spaces +
429 on + the + second + and + subsequent + lines;
433 Do not add whitespace at the end of a line, and only use tabs
435 to form the indentation.
436 Do not use more spaces than a tab will produce
437 and do not use spaces in front of tabs.
439 Closing and opening braces go on the same line as the
441 Braces that are not necessary may be left out, but always use braces around
442 complex or confusing sequences, for example if any part of a conditional is
443 multi-line, use braces for all parts of the conditional, and use braces
444 around multi-line substatements of loops or conditionals even if they are
445 theoretically one statement from the compiler's point of view.
463 /* THIS IS WRONG, BRACES SHOULD BE USED */
468 /* THIS IS ALSO WRONG, USE BRACES AROUND THE OUTER CONDITIONAL */
474 Do not put spaces after function names,
479 characters, or preceding
486 But do put a space after commas and semicolons if there is
487 further text on the same line.
489 error = function(a1, a2);
494 Unary operators do not require spaces around them,
495 but binary operators (except for
500 Do not use parentheses unless they are required for precedence or unless the
501 statement is confusing without them.
502 Remember that other people may become
503 confused more easily than you.
504 Do YOU understand the following?
506 a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
510 Casts are not followed by a space.
513 does not understand this rule.
514 Also, for the purposes of formatting, treat
518 as functions. In other words, they are not
519 followed by a space, and their single argument
520 should be enclosed in parentheses.
522 Exits should be 0 on success, or according to the predefined
527 * Avoid obvious comments such as
528 * "Exit 0 on success."
533 The function type should be on a line by itself
534 preceding the function.
537 function(int a1, int a2, float fl, int a4)
541 When declaring variables in functions declare them sorted by size,
542 then in alphabetical order; multiple ones per line are okay.
543 If a line overflows reuse the type keyword.
545 Be careful to not obfuscate the code by initializing variables in
547 Use this feature only thoughtfully.
548 DO NOT use function calls in initializers.
550 struct foo one, *two;
553 char *six, seven, eight, nine, ten, eleven, twelve;
558 Do not declare functions inside other functions; ANSI C says that
559 such declarations have file scope regardless of the nesting of the
561 Hiding file declarations in what appears to be a local
562 scope is undesirable and will elicit complaints from a good compiler.
565 is the preferred null pointer constant.
569 .Vt ( "type *" ) Ns 0
571 .Vt ( "type *" ) Ns Dv NULL
572 in contexts where the compiler knows the
573 type, e.g., in assignments.
575 .Vt ( "type *" ) Ns Dv NULL
577 in particular for all function args.
578 (Casting is essential for
579 variadic args and is necessary for other args if the function prototype
580 might not be in scope.)
581 Test pointers against
595 for tests unless it is a boolean, e.g. use
605 Do not cast the unused return value of a function to (void).
609 should not have their return values cast
616 do not roll your own.
618 if ((four = malloc(sizeof(struct foo))) == NULL)
620 if ((six = (int *)overflow()) == NULL)
621 errx(1, "number overflowed");
626 Avoid old-style function declarations that look like this:
629 function(a1, a2, fl, a4)
630 int a1, a2; /* Declare ints, too, don't default them. */
631 float fl; /* Beware double vs. float prototype differences. */
632 int a4; /* List in order declared. */
636 Use ANSI function declarations instead.
637 Long parameter lists are wrapped so that the first parameter on each line
640 Try to avoid using obsolete functions such as:
650 All new code must avoid using unbounded string functions. For example,
652 should be used instead of
656 should be used instead of
659 Varargs procedures should be formatted as follows:
664 vaf(const char *fmt, ...)
671 /* No return needed for void functions. */
681 whatever; it is faster and usually cleaner, not
682 to mention avoiding stupid bugs.
684 Usage statements should look like the manual pages
686 The usage statement should be structured in the following order:
689 Options without operands come first,
690 in alphabetical order,
691 inside a single set of brackets
696 Options with operands come next,
697 also in alphabetical order,
698 with each option and its argument inside its own pair of brackets.
703 listed in the order they should be specified on the command line.
706 any optional arguments should be listed,
707 listed in the order they should be specified,
708 and all inside brackets.
716 and multiple options/arguments which are specified together are
717 placed in a single set of brackets.
718 .Bd -literal -offset 4n
719 "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
720 "usage: f [-a | -b] [-c [-dEe] [-n number]]\en"
723 fprintf(stderr, "usage: f [-ab]\en");
728 Note that the manual page options description should list the options in
729 pure alphabetical order.
730 That is, without regard to whether an option takes arguments or not.
731 The alphabetical ordering should take into account the case ordering
734 New core kernel code should be reasonably compliant with the
737 The guidelines for third-party maintained modules and device drivers are more
738 relaxed but at a minimum should be internally consistent with their style.
740 Stylistic changes (including whitespace changes) are hard on the source
741 repository and are to be avoided without good reason.
742 Code that is approximately
746 compliant in the repository must not diverge from compliance.
748 Whenever possible, code should be run through a code checker
753 and produce minimal warnings.
761 This man page is largely based on the
762 .Pa src/admin/style/style
765 release, with occasional updates to reflect the current practice and