Don't use parameter names for kernel prototyps
[dragonfly.git] / share / man / man9 / style.9
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.