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