There are historically two families of fixed size integers, u_intX_t and
[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.7 2004/02/27 11:27:39 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 As fixed size integers the \*[Px] defined types are prefered:
183 .Bd -literal -offset indent
184 uint8_t         8 bits fixed size unsigned integer
185 uint16_t        16 bits fixed size unsigned integer
186 uint32_t        32 bits fixed size unsigned integer
187 uint64_t        64 bits fixed size unsigned integer
188 .Ed
189 .Pp
190 When declaring variables in structures, declare them sorted by use, then
191 by size, and then in alphabetical order.
192 The first category normally does not apply, but there are exceptions.
193 Each one gets its own line.
194 Try to make the structure
195 readable by aligning the member names using either one or two tabs
196 depending upon your judgment.
197 You should use one tab if it suffices to align most of the member names.
198 Names following extremely long types
199 should be separated by a single space.
200 .Pp
201 Major structures should be declared at the top of the file in which they
202 are used, or in separate header files if they are used in multiple
203 source files.
204 Use of the structures should be by separate declarations
205 and should be
206 .Ic extern
207 if they are declared in a header file.
208 .Bd -literal
209 struct foo {
210         struct foo      *next;          /* List of active foo. */
211         struct mumble   amumble;        /* Comment for mumble. */
212         int             bar;            /* Try to align the comments. */
213         struct verylongtypename *baz;   /* Won't fit in 2 tabs. */
214 };
215 struct foo *foohead;                    /* Head of global foo list. */
216 .Ed
217 .Pp
218 Use
219 .Xr queue 3
220 macros rather than rolling your own lists, whenever possible.
221 Thus,
222 the previous example would be better written:
223 .Bd -literal
224 #include <sys/queue.h>
225
226 struct foo {
227         LIST_ENTRY(foo) link;           /* Use queue macros for foo lists. */
228         struct mumble   amumble;        /* Comment for mumble. */
229         int             bar;            /* Try to align the comments. */
230         struct verylongtypename *baz;   /* Won't fit in 2 tabs. */
231 };
232 LIST_HEAD(, foo) foohead;               /* Head of global foo list. */
233 .Ed
234 .Pp
235 Avoid using typedefs for structure types.
236 This makes it impossible
237 for applications to use pointers to such a structure opaquely, which
238 is both possible and beneficial when using an ordinary struct tag.
239 When convention requires a
240 .Ic typedef ,
241 make its name match the struct tag.
242 Avoid typedefs ending in
243 .Dq Li _t ,
244 except as specified in Standard C or by \*[Px].
245 .Bd -literal
246 /* Make the structure name match the typedef. */
247 typedef struct bar {
248         int     level;
249 } BAR;
250 typedef int             foo;            /* This is foo. */
251 typedef const long      baz;            /* This is baz. */
252 .Ed
253 .Pp
254 All functions are prototyped somewhere.
255 .Pp
256 Function prototypes for private functions (i.e. functions not used
257 elsewhere) go at the top of the first source module.
258 Functions
259 local to one source module should be declared
260 .Ic static .
261 .Pp
262 Functions used from other parts of the kernel are prototyped in the
263 relevant include file.
264 .Pp
265 Functions that are used locally in more than one module go into a
266 separate header file, e.g.\&
267 .Qq Pa extern.h .
268 .Pp
269 Avoid using the
270 .Dv __P
271 macro from the include file
272 .Aq Pa sys/cdefs.h .
273 Code in the DragonFly source tree is not
274 expected to be K&R compliant.
275 .Pp
276 Changes to existing files should be consistent with that file's conventions.
277 In general, code can be considered
278 .Dq "new code"
279 when it makes up about 50% or more of the file(s) involved.
280 This is enough
281 to break precedents in the existing code and use the current
282 .Nm
283 guidelines.
284 .Pp
285 Function prototypes for the kernel have parameter names associated
286 with parameter types. E.g., in the kernel use:
287 .Bd -literal
288 void    function(int fd);
289 .Ed
290 .Pp
291 Prototypes that are visible to userland applications
292 should not include parameter names with the types, to avoid
293 possible collisions with defined macro names.
294 I.e., use:
295 .Bd -literal
296 void    function(int);
297 .Ed
298 .Pp
299 Prototypes may have an extra space after a tab to enable function names
300 to line up:
301 .Bd -literal
302 static char     *function(int _arg, const char *_arg2, struct foo *_arg3,
303                     struct bar *_arg4);
304 static void      usage(void);
305
306 /*
307  * All major routines should have a comment briefly describing what
308  * they do.  The comment before the "main" routine should describe
309  * what the program does.
310  */
311 int
312 main(int argc, char *argv[])
313 {
314         long num;
315         int ch;
316         char *ep;
317
318 .Ed
319 .Pp
320 For consistency,
321 .Xr getopt 3
322 should be used to parse options.
323 Options
324 should be sorted in the
325 .Xr getopt 3
326 call and the
327 .Ic switch
328 statement, unless
329 parts of the
330 .Ic switch
331 cascade.
332 Elements in a
333 .Ic switch
334 statement that cascade should have a
335 .Li FALLTHROUGH
336 comment.
337 Numerical arguments should be checked for accuracy.
338 Code that cannot be reached should have a
339 .Li NOTREACHED
340 comment.
341 .Bd -literal
342         while ((ch = getopt(argc, argv, "abn:")) != -1)
343                 switch (ch) {           /* Indent the switch. */
344                 case 'a':               /* Don't indent the case. */
345                         aflag = 1;
346                         /* FALLTHROUGH */
347                 case 'b':
348                         bflag = 1;
349                         break;
350                 case 'n':
351                         num = strtol(optarg, &ep, 10);
352                         if (num <= 0 || *ep != '\e0') {
353                                 warnx("illegal number, -n argument -- %s",
354                                     optarg);
355                                 usage();
356                         }
357                         break;
358                 case '?':
359                 default:
360                         usage();
361                         /* NOTREACHED */
362                 }
363         argc -= optind;
364         argv += optind;
365 .Ed
366 .Pp
367 Space after keywords
368 .Pq Ic if , while , for , return , switch .
369 No braces are
370 used for control statements with zero or only a single statement unless that
371 statement is more than a single line in which case they are permitted.
372 Forever loops are done with
373 .Ic for Ns 's ,
374 not
375 .Ic while Ns 's .
376 .Bd -literal
377         for (p = buf; *p != '\e0'; ++p)
378                 ;       /* nothing */
379         for (;;)
380                 stmt;
381         for (;;) {
382                 z = a + really + long + statement + that + needs +
383                     two lines + gets + indented + four + spaces +
384                     on + the + second + and + subsequent + lines;
385         }
386         for (;;) {
387                 if (cond)
388                         stmt;
389         }
390         if (val != NULL)
391                 val = realloc(val, newsize);
392 .Ed
393 .Pp
394 Parts of a
395 .Ic for
396 loop may be left empty.
397 Do not put declarations
398 inside blocks unless the routine is unusually complicated.
399 .Bd -literal
400         for (; cnt < 15; cnt++) {
401                 stmt1;
402                 stmt2;
403         }
404 .Ed
405 .Pp
406 Indentation used for program block structure is an 8 character tab.
407 Second level indents used for line continuation are four spaces.
408 If you have to wrap a long statement, put the operator at the end of the
409 line.
410 .Bd -literal
411         while (cnt < 20 && this_variable_name_is_really_far_too_long &&
412             ep != NULL)
413                 z = a + really + long + statement + that + needs +
414                     two lines + gets + indented + four + spaces +
415                     on + the + second + and + subsequent + lines;
416 .Ed
417 .Pp
418 Do not add whitespace at the end of a line, and only use tabs
419 followed by spaces
420 to form the indentation.
421 Do not use more spaces than a tab will produce
422 and do not use spaces in front of tabs.
423 .Pp
424 Closing and opening braces go on the same line as the
425 .Ic else .
426 Braces that are not necessary may be left out.
427 .Bd -literal
428         if (test)
429                 stmt;
430         else if (bar) {
431                 stmt;
432                 stmt;
433         } else
434                 stmt;
435 .Ed
436 .Pp
437 No spaces after function names.
438 Commas have a space after them.
439 No spaces
440 after
441 .Ql \&(
442 or
443 .Ql \&[
444 or preceding
445 .Ql \&]
446 or
447 .Ql \&)
448 characters.
449 .Bd -literal
450         error = function(a1, a2);
451         if (error != 0)
452                 exit(error);
453 .Ed
454 .Pp
455 Unary operators do not require spaces, binary operators do.
456 Do not use parentheses unless they are required for precedence or unless the
457 statement is confusing without them.
458 Remember that other people may become
459 confused more easily than you.
460 Do YOU understand the following?
461 .Bd -literal
462         a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
463         k = !(l & FLAGS);
464 .Ed
465 .Pp
466 Exits should be 0 on success, or according to the predefined
467 values in
468 .Xr sysexits 3 .
469 .Bd -literal
470         exit(EX_OK);    /*
471                          * Avoid obvious comments such as
472                          * "Exit 0 on success."
473                          */
474 }
475 .Ed
476 .Pp
477 The function type should be on a line by itself
478 preceding the function.
479 .Bd -literal
480 static char *
481 function(int a1, int a2, float fl, int a4)
482 {
483 .Ed
484 .Pp
485 When declaring variables in functions declare them sorted by size,
486 then in alphabetical order; multiple ones per line are okay.
487 If a line overflows reuse the type keyword.
488 .Pp
489 Be careful to not obfuscate the code by initializing variables in
490 the declarations.
491 Use this feature only thoughtfully.
492 DO NOT use function calls in initializers.
493 .Bd -literal
494         struct foo one, *two;
495         double three;
496         int *four, five;
497         char *six, seven, eight, nine, ten, eleven, twelve;
498
499         four = myfunction();
500 .Ed
501 .Pp
502 Do not declare functions inside other functions; ANSI C says that
503 such declarations have file scope regardless of the nesting of the
504 declaration.
505 Hiding file declarations in what appears to be a local
506 scope is undesirable and will elicit complaints from a good compiler.
507 .Pp
508 Casts are not followed by a space.
509 Note that
510 .Xr indent 1
511 does not understand this rule.
512 .Pp
513 For the purposes of formatting, treat
514 .Ic return
515 and
516 .Ic sizeof
517 as functions.  In other words, they are not
518 followed by a space, and their single argument
519 should be enclosed in parentheses.
520 .Pp
521 .Dv NULL
522 is the preferred null pointer constant.
523 Use
524 .Dv NULL
525 instead of
526 .Vt ( "type *" ) Ns 0
527 or
528 .Vt ( "type *" ) Ns Dv NULL
529 in contexts where the compiler knows the
530 type, e.g., in assignments.
531 Use
532 .Vt ( "type *" ) Ns Dv NULL
533 in other contexts,
534 in particular for all function args.
535 (Casting is essential for
536 variadic args and is necessary for other args if the function prototype
537 might not be in scope.)
538 Test pointers against
539 .Dv NULL ,
540 e.g., use:
541 .Pp
542 .Bd -literal
543 (p = f()) == NULL
544 .Ed
545 .Pp
546 not:
547 .Bd -literal
548 !(p = f())
549 .Ed
550 .Pp
551 Do not use
552 .Ic \&!
553 for tests unless it is a boolean, e.g. use
554 .Bd -literal
555 if (*p == '\e0')
556 .Ed
557 .Pp
558 not
559 .Bd -literal
560 if (!*p)
561 .Ed
562 .Pp
563 Routines returning
564 .Vt "void *"
565 should not have their return values cast
566 to any pointer type.
567 .Pp
568 Use
569 .Xr err 3
570 or
571 .Xr warn 3 ,
572 do not roll your own.
573 .Bd -literal
574         if ((four = malloc(sizeof(struct foo))) == NULL)
575                 err(1, (char *)NULL);
576         if ((six = (int *)overflow()) == NULL)
577                 errx(1, "number overflowed");
578         return (eight);
579 }
580 .Ed
581 .Pp
582 Avoid old-style function declarations that look like this:
583 .Bd -literal
584 static char *
585 function(a1, a2, fl, a4)
586         int a1, a2;     /* Declare ints, too, don't default them. */
587         float fl;       /* Beware double vs. float prototype differences. */
588         int a4;         /* List in order declared. */
589 {
590 .Ed
591 .Pp
592 Use ANSI function declarations instead.
593 Long parameter lists are wrapped with a normal four space indent.
594 .Pp
595 Variable numbers of arguments should look like this.
596 .Bd -literal
597 #include <stdarg.h>
598
599 void
600 vaf(const char *fmt, ...)
601 {
602         va_list ap;
603
604         va_start(ap, fmt);
605         STUFF;
606         va_end(ap);
607         /* No return needed for void functions. */
608 }
609
610 static void
611 usage(void)
612 {
613         /* Insert an empty line if the function has no local variables. */
614 .Ed
615 .Pp
616 Use
617 .Xr printf 3 ,
618 not
619 .Xr fputs 3 ,
620 .Xr puts 3 ,
621 .Xr putchar 3 ,
622 whatever; it is faster and usually cleaner, not
623 to mention avoiding stupid bugs.
624 .Pp
625 Usage statements should look like the manual pages
626 .Sx SYNOPSIS .
627 The usage statement should be structured in the following order:
628 .Bl -enum
629 .It
630 Options without operands come first,
631 in alphabetical order,
632 inside a single set of brackets
633 .Ql ( \&[
634 and
635 .Ql \&] ) .
636 .It
637 Options with operands come next,
638 also in alphabetical order,
639 with each option and its argument inside its own pair of brackets.
640 .It
641 Required arguments
642 (if any)
643 are next,
644 listed in the order they should be specified on the command line.
645 .It
646 Finally,
647 any optional arguments should be listed,
648 listed in the order they should be specified,
649 and all inside brackets.
650 .El
651 .Pp
652 A bar
653 .Pq Ql \&|
654 separates
655 .Dq either-or
656 options/arguments,
657 and multiple options/arguments which are specified together are
658 placed in a single set of brackets.
659 .Bd -literal -offset 4n
660 "usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
661 "usage: f [-a | -b] [-c [-dEe] [-n number]]\en"
662 .Ed
663 .Bd -literal
664         (void)fprintf(stderr, "usage: f [-ab]\en");
665         exit(EX_USAGE);
666 }
667 .Ed
668 .Pp
669 Note that the manual page options description should list the options in
670 pure alphabetical order.
671 That is, without regard to whether an option takes arguments or not.
672 The alphabetical ordering should take into account the case ordering
673 shown above.
674 .Pp
675 New core kernel code should be reasonably compliant with the
676 .Nm
677 guides.
678 The guidelines for third-party maintained modules and device drivers are more
679 relaxed but at a minimum should be internally consistent with their style.
680 .Pp
681 Stylistic changes (including whitespace changes) are hard on the source
682 repository and are to be avoided without good reason.
683 Code that is approximately
684 .Fx
685 KNF
686 .Nm
687 compliant in the repository must not diverge from compliance.
688 .Pp
689 Whenever possible, code should be run through a code checker
690 (e.g.,
691 .Xr lint 1
692 or
693 .Nm gcc Fl Wall )
694 and produce minimal warnings.
695 .Sh SEE ALSO
696 .Xr indent 1 ,
697 .Xr lint 1 ,
698 .Xr err 3 ,
699 .Xr sysexits 3 ,
700 .Xr warn 3
701 .Sh HISTORY
702 This man page is largely based on the
703 .Pa src/admin/style/style
704 file from the
705 .Bx 4.4 Lite2
706 release, with occasional updates to reflect the current practice and
707 desire of the
708 .Fx
709 project.