xref: /freebsd-13-stable/share/man/man9/style.9 (revision cecda19fd6bf54f0d009b54ea8b092745d607443)
1.\"-
2.\" Copyright (c) 1995-2019 The FreeBSD Project
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.\"	From: @(#)style	1.14 (Berkeley) 4/28/95
26.\"
27.Dd April 26, 2024
28.Dt STYLE 9
29.Os
30.Sh NAME
31.Nm style
32.Nd "kernel source file style guide"
33.Sh DESCRIPTION
34This file specifies the preferred style for kernel source files in the
35.Fx
36source tree.
37It is also a guide for the preferred userland code style.
38Many of the style rules are implicit in the examples.
39Be careful to check the examples before assuming that
40.Nm
41is silent on an issue.
42.Bd -literal
43/*
44 * Style guide for FreeBSD.  Based on the CSRG's KNF (Kernel Normal Form).
45 *
46 *	@(#)style	1.14 (Berkeley) 4/28/95
47 */
48
49/*
50 * VERY important single-line comments look like this.
51 */
52
53/* Most single-line comments look like this. */
54
55/*
56 * Multi-line comments look like this.  Make them real sentences.  Fill
57 * them so they look like real paragraphs.
58 */
59.Ed
60.Pp
61The copyright header should be a multi-line comment, with the first
62line of the comment having a dash after the star like so:
63.Bd -literal
64/*-
65 * SPDX-License-Identifier: BSD-2-Clause
66 *
67 * Copyright (c) 1984-2025 John Q. Public
68 *
69 * Long, boring license goes here, but trimmed for brevity
70 */
71.Ed
72.Pp
73An automatic script collects license information from the tree for
74all comments that start in the first column with
75.Dq Li "/*-" .
76If you desire to flag
77.Xr indent 1
78to not reformat a comment that starts in the first column which is not a
79license or copyright notice, change the dash to a star for those
80comments.
81Comments starting in columns other than the first are never
82considered license statements.
83Use the appropriate SPDX-License-Identifier line before the copyright.
84If the copyright assertion contains the phrase
85.Dq Li "All Rights Reserved"
86that should be on the same line as the word
87.Dq Li "Copyright" .
88You should not insert a new copyright line between an old
89copyright line and this phrase.
90Instead, you should insert a new copyright phrase after
91a pre-existing
92.Dq Li "All Rights Reserved"
93line.
94When making changes, it is acceptable to fold an
95.Dq Li "All Rights Reserved"
96line with each of the
97.Dq Li "Copyright"
98lines.
99For files that have the
100.Dq Li "All Rights Reserved"
101line on the same line(s) as the word
102.Dq Li "Copyright" ,
103new copyright assertions should be added last.
104New
105.Dq Li "Copyright"
106lines should only be added when making substantial changes to the file,
107not for trivial changes.
108.Pp
109After any copyright and license comment, there is a blank line, and the
110.Li $\&FreeBSD$
111for non C/C++ language source files.
112Version control system ID tags should only exist once in a file
113(unlike in this one).
114Non-C/C++ source files follow the example above, while C/C++ source files
115follow the one below.
116All VCS (version control system) revision identification in files obtained
117from elsewhere should be maintained, including, where applicable, multiple IDs
118showing a file's history.
119In general, do not edit foreign IDs or their infrastructure.
120Unless otherwise wrapped (such as
121.Dq Li "#if defined(LIBC_SCCS)" ) ,
122enclose both in
123.Dq Li "#if 0 ... #endif"
124to hide any uncompilable bits
125and to keep the IDs out of object files.
126Only add
127.Dq Li "From: "
128in front of foreign VCS IDs if the file is renamed.
129.Bd -literal
130/* From: @(#)style	1.14 (Berkeley) 4/28/95 */
131
132#include <sys/cdefs.h>
133.Ed
134.Pp
135Leave one blank line before the header files.
136.Pp
137Kernel include files
138.Pa ( sys/*.h )
139come first.
140If
141.In sys/cdefs.h
142is needed for
143.Fn __FBSDID ,
144include it first.
145If either
146.In sys/types.h
147or
148.In sys/param.h
149is needed, include it before other include files.
150.Po
151.In sys/param.h
152includes
153.In sys/types.h ;
154do not include both.
155.Pc
156Next, include
157.In sys/systm.h ,
158if needed.
159The remaining kernel headers should be sorted alphabetically.
160.Bd -literal
161#include <sys/types.h>	/* Non-local includes in angle brackets. */
162#include <sys/systm.h>
163#include <sys/endian.h>
164#include <sys/lock.h>
165#include <sys/queue.h>
166.Ed
167.Pp
168For a network program, put the network include files next.
169.Bd -literal
170#include <net/if.h>
171#include <net/if_dl.h>
172#include <net/route.h>
173#include <netinet/in.h>
174#include <protocols/rwhod.h>
175.Ed
176.Pp
177Do not include files from
178.Pa /usr/include
179in the kernel.
180.Pp
181Leave a blank line before the next group, the
182.Pa /usr/include
183files,
184which should be sorted alphabetically by name.
185.Bd -literal
186#include <stdio.h>
187.Ed
188.Pp
189Global pathnames are defined in
190.In paths.h .
191Pathnames local
192to the program go in
193.Qq Pa pathnames.h
194in the local directory.
195.Bd -literal
196#include <paths.h>
197.Ed
198.Pp
199Leave another blank line before the local include files.
200.Bd -literal
201#include "pathnames.h"		/* Local includes in double quotes. */
202.Ed
203.Pp
204Do not
205.Ic #define
206or declare names in the implementation namespace except
207for implementing application interfaces.
208.Pp
209The names of
210.Dq unsafe
211macros (ones that have side effects), and the names of macros for
212manifest constants, are all in uppercase.
213The expansions of expression-like macros are either a single token
214or have outer parentheses.
215Put a single tab character between the
216.Ic #define
217and the macro name.
218If a macro is an inline expansion of a function, the function name is
219all in lowercase and the macro has the same name all in uppercase.
220.\" XXX the above conflicts with ANSI style where the names are the
221.\" same and you #undef the macro (if any) to get the function.
222.\" It is not followed for MALLOC(), and not very common if inline
223.\" functions are used.
224Right-justify the
225backslashes; it makes it easier to read.
226If the macro encapsulates a compound statement, enclose it in a
227.Ic do
228loop,
229so that it can safely be used in
230.Ic if
231statements.
232Any final statement-terminating semicolon should be
233supplied by the macro invocation rather than the macro, to make parsing easier
234for pretty-printers and editors.
235.Bd -literal
236#define	MACRO(x, y) do {						\e
237	variable = (x) + (y);						\e
238	(y) += 2;							\e
239} while (0)
240.Ed
241.Pp
242When code is conditionally compiled using
243.Ic #ifdef
244or
245.Ic #if ,
246a comment may be added following the matching
247.Ic #endif
248or
249.Ic #else
250to permit the reader to easily discern where conditionally compiled code
251regions end.
252This comment should be used only for (subjectively) long regions, regions
253greater than 20 lines, or where a series of nested
254.Ic #ifdef 's
255may be confusing to the reader.
256The comment should be separated from the
257.Ic #endif
258or
259.Ic #else
260by a single space.
261For short conditionally compiled regions, a closing comment should not be
262used.
263.Pp
264The comment for
265.Ic #endif
266should match the expression used in the corresponding
267.Ic #if
268or
269.Ic #ifdef .
270The comment for
271.Ic #else
272and
273.Ic #elif
274should match the inverse of the expression(s) used in the preceding
275.Ic #if
276and/or
277.Ic #elif
278statements.
279In the comments, the subexpression
280.Dq Li defined(FOO)
281is abbreviated as
282.Dq Li FOO .
283For the purposes of comments,
284.Dq Ic #ifndef Li FOO
285is treated as
286.Dq Ic #if Li !defined(FOO) .
287.Bd -literal
288#ifdef KTRACE
289#include <sys/ktrace.h>
290#endif
291
292#ifdef COMPAT_43
293/* A large region here, or other conditional code. */
294#else /* !COMPAT_43 */
295/* Or here. */
296#endif /* COMPAT_43 */
297
298#ifndef COMPAT_43
299/* Yet another large region here, or other conditional code. */
300#else /* COMPAT_43 */
301/* Or here. */
302#endif /* !COMPAT_43 */
303.Ed
304.Pp
305The project prefers the use of
306.St -isoC-99
307unsigned integer identifiers of the form
308.Vt uintXX_t
309rather than the older
310.Bx Ns -style
311integer identifiers of the form
312.Vt u_intXX_t .
313New code should use the former, and old code should be converted to
314the new form if other major work is being done in that area and
315there is no overriding reason to prefer the older
316.Bx Ns -style .
317Like white-space commits, care should be taken in making
318.Vt uintXX_t
319only commits.
320.Pp
321Similarly, the project prefers the use of
322ISO C99
323.Vt bool
324rather than the older
325.Vt int
326or
327.Vt boolean_t .
328New code should use
329.Vt bool ,
330and old code may be converted if it is
331reasonable to do so.
332Literal values are named
333.Dv true
334and
335.Dv false .
336These are preferred to the old spellings
337.Dv TRUE
338and
339.Dv FALSE .
340Userspace code should include
341.In stdbool.h ,
342while kernel code should include
343.In sys/types.h .
344.Pp
345Likewise, the project prefers
346ISO C99
347designated initializers when it makes sense to do so.
348.Pp
349Enumeration values are all uppercase.
350.Bd -literal
351enum enumtype { ONE, TWO } et;
352.Ed
353.Pp
354The use of internal_underscores in identifiers is preferred over
355camelCase or TitleCase.
356.Pp
357In declarations, do not put any whitespace between asterisks and
358adjacent tokens, except for tokens that are identifiers related to
359types.
360(These identifiers are the names of basic types, type
361qualifiers, and
362.Ic typedef Ns -names
363other than the one being declared.)
364Separate these identifiers from asterisks using a single space.
365.Pp
366When declaring variables in structures, declare them sorted by use, then
367by size (largest to smallest), and then in alphabetical order.
368The first category normally does not apply, but there are exceptions.
369Each one gets its own line.
370Try to make the structure
371readable by aligning the member names using either one or two tabs
372depending upon your judgment.
373You should use one tab only if it suffices to align at least 90% of
374the member names.
375Names following extremely long types
376should be separated by a single space.
377.Pp
378Major structures should be declared at the top of the file in which they
379are used, or in separate header files if they are used in multiple
380source files.
381Use of the structures should be by separate declarations
382and should be
383.Ic extern
384if they are declared in a header file.
385.Bd -literal
386struct foo {
387	struct foo	*next;		/* List of active foo. */
388	struct mumble	amumble;	/* Comment for mumble. */
389	int		bar;		/* Try to align the comments. */
390	struct verylongtypename *baz;	/* Does not fit in 2 tabs. */
391};
392struct foo *foohead;			/* Head of global foo list. */
393.Ed
394.Pp
395Use
396.Xr queue 3
397macros rather than rolling your own lists, whenever possible.
398Thus,
399the previous example would be better written:
400.Bd -literal
401#include <sys/queue.h>
402
403struct foo {
404	LIST_ENTRY(foo)	link;		/* Use queue macros for foo lists. */
405	struct mumble	amumble;	/* Comment for mumble. */
406	int		bar;		/* Try to align the comments. */
407	struct verylongtypename *baz;	/* Does not fit in 2 tabs. */
408};
409LIST_HEAD(, foo) foohead;		/* Head of global foo list. */
410.Ed
411.Pp
412Avoid using typedefs for structure types.
413Typedefs are problematic because they do not properly hide their
414underlying type; for example you need to know if the typedef is
415the structure itself or a pointer to the structure.
416In addition they must be declared exactly once, whereas an
417incomplete structure type can be mentioned as many times as
418necessary.
419Typedefs are difficult to use in stand-alone header files:
420the header that defines the typedef must be included
421before the header that uses it, or by the header that uses
422it (which causes namespace pollution), or there must be a
423back-door mechanism for obtaining the typedef.
424.Pp
425When convention requires a
426.Ic typedef ,
427make its name match the struct tag.
428Avoid typedefs ending in
429.Dq Li _t ,
430except as specified in Standard C or by POSIX.
431.Bd -literal
432/* Make the structure name match the typedef. */
433typedef	struct bar {
434	int	level;
435} BAR;
436typedef	int		foo;		/* This is foo. */
437typedef	const long	baz;		/* This is baz. */
438.Ed
439.Pp
440All functions are prototyped somewhere.
441.Pp
442Function prototypes for private functions (i.e., functions not used
443elsewhere) go at the top of the first source module.
444Functions
445local to one source module should be declared
446.Ic static .
447.Pp
448Functions used from other parts of the kernel are prototyped in the
449relevant include file.
450Function prototypes should be listed in a logical order, preferably
451alphabetical unless there is a compelling reason to use a different
452ordering.
453.Pp
454Functions that are used locally in more than one module go into a
455separate header file, e.g.,
456.Qq Pa extern.h .
457.Pp
458Do not use the
459.Dv __P
460macro.
461.Pp
462In general code can be considered
463.Dq "new code"
464when it makes up about 50% or more of the file(s) involved.
465This is enough
466to break precedents in the existing code and use the current
467.Nm
468guidelines.
469.Pp
470The kernel has a name associated with parameter types, e.g., in the kernel
471use:
472.Bd -literal
473void	function(int fd);
474.Ed
475.Pp
476In header files visible to userland applications, prototypes that are
477visible must use either
478.Dq protected
479names (ones beginning with an underscore)
480or no names with the types.
481It is preferable to use protected names.
482E.g., use:
483.Bd -literal
484void	function(int);
485.Ed
486.Pp
487or:
488.Bd -literal
489void	function(int _fd);
490.Ed
491.Pp
492Prototypes may have an extra space after a tab to enable function names
493to line up:
494.Bd -literal
495static char	*function(int _arg, const char *_arg2, struct foo *_arg3,
496		    struct bar *_arg4);
497static void	 usage(void);
498
499/*
500 * All major routines should have a comment briefly describing what
501 * they do.  The comment before the "main" routine should describe
502 * what the program does.
503 */
504int
505main(int argc, char *argv[])
506{
507	char *ep;
508	long num;
509	int ch;
510.Ed
511.Pp
512For consistency,
513.Xr getopt 3
514should be used to parse options.
515Options
516should be sorted in the
517.Xr getopt 3
518call and the
519.Ic switch
520statement, unless
521parts of the
522.Ic switch
523cascade.
524Elements in a
525.Ic switch
526statement that cascade should have a
527.Li FALLTHROUGH
528comment.
529Numerical arguments should be checked for accuracy.
530Code which is unreachable for non-obvious reasons may be marked /*
531.Li NOTREACHED
532*/.
533.Bd -literal
534	while ((ch = getopt(argc, argv, "abNn:")) != -1)
535		switch (ch) {		/* Indent the switch. */
536		case 'a':		/* Do not indent the case. */
537			aflag = 1;	/* Indent case body one tab. */
538			/* FALLTHROUGH */
539		case 'b':
540			bflag = 1;
541			break;
542		case 'N':
543			Nflag = 1;
544			break;
545		case 'n':
546			num = strtol(optarg, &ep, 10);
547			if (num <= 0 || *ep != '\e0') {
548				warnx("illegal number, -n argument -- %s",
549				    optarg);
550				usage();
551			}
552			break;
553		case '?':
554		default:
555			usage();
556		}
557	argc -= optind;
558	argv += optind;
559.Ed
560.Pp
561Space after keywords
562.Pq Ic if , while , for , return , switch .
563Two styles of braces
564.Ql ( \&{
565and
566.Ql \&} )
567are allowed for single line statements.
568Either they are used for all single statements, or
569they are used only where needed for clarity.
570Usage within a function should be consistent.
571Forever loops are done with
572.Ic for Ns 's ,
573not
574.Ic while Ns 's .
575.Bd -literal
576	for (p = buf; *p != '\e0'; ++p)
577		;	/* nothing */
578	for (;;)
579		stmt;
580	for (;;) {
581		z = a + really + long + statement + that + needs +
582		    two + lines + gets + indented + four + spaces +
583		    on + the + second + and + subsequent + lines;
584	}
585	for (;;) {
586		if (cond)
587			stmt;
588	}
589	if (val != NULL)
590		val = realloc(val, newsize);
591.Ed
592.Pp
593Parts of a
594.Ic for
595loop may be left empty.
596.Bd -literal
597	for (; cnt < 15; cnt++) {
598		stmt1;
599		stmt2;
600	}
601.Ed
602.Pp
603A
604.Ic for
605loop may declare and initialize its counting variable.
606.Bd -literal
607	for (int i = 0; i < 15; i++) {
608		stmt1;
609	}
610.Ed
611.Pp
612Indentation is an 8 character tab.
613Second level indents are four spaces.
614If you have to wrap a long statement, put the operator at the end of the
615line.
616.Bd -literal
617	while (cnt < 20 && this_variable_name_is_too_long &&
618	    ep != NULL)
619		z = a + really + long + statement + that + needs +
620		    two + lines + gets + indented + four + spaces +
621		    on + the + second + and + subsequent + lines;
622.Ed
623.Pp
624Do not add whitespace at the end of a line, and only use tabs
625followed by spaces
626to form the indentation.
627Do not use more spaces than a tab will produce
628and do not use spaces in front of tabs.
629.Pp
630Closing and opening braces go on the same line as the
631.Ic else .
632Braces that are not necessary may be left out.
633.Bd -literal
634	if (test)
635		stmt;
636	else if (bar) {
637		stmt;
638		stmt;
639	} else
640		stmt;
641.Ed
642.Pp
643No spaces after function names.
644Commas have a space after them.
645No spaces
646after
647.Ql \&(
648or
649.Ql \&[
650or preceding
651.Ql \&]
652or
653.Ql \&)
654characters.
655.Bd -literal
656	error = function(a1, a2);
657	if (error != 0)
658		exit(error);
659.Ed
660.Pp
661Unary operators do not require spaces, binary operators do.
662Do not use parentheses unless they are required for precedence or unless the
663statement is confusing without them.
664Remember that other people may
665confuse easier than you.
666Do YOU understand the following?
667.Bd -literal
668	a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
669	k = !(l & FLAGS);
670.Ed
671.Pp
672Exits should be 0 on success, or 1 on failure.
673.Bd -literal
674	exit(0);	/*
675			 * Avoid obvious comments such as
676			 * "Exit 0 on success."
677			 */
678}
679.Ed
680.Pp
681The function type should be on a line by itself
682preceding the function.
683The opening brace of the function body should be
684on a line by itself.
685.Bd -literal
686static char *
687function(int a1, int a2, float fl, int a4, struct bar *bar)
688{
689.Ed
690.Pp
691When declaring variables in functions declare them sorted by size,
692then in alphabetical order; multiple ones per line are okay.
693If a line overflows reuse the type keyword.
694Variables may be initialized where declared especially when they
695are constant for the rest of the scope.
696Declarations may be placed before executable lines at the start
697of any block.
698Calls to complicated functions should be avoided when initializing variables.
699.Bd -literal
700	struct foo one, *two;
701	struct baz *three = bar_get_baz(bar);
702	double four;
703	int *five, six;
704	char *seven, eight, nine, ten, eleven, twelve;
705
706	four = my_complicated_function(a1, f1, a4);
707.Ed
708.Pp
709Do not declare functions inside other functions; ANSI C says that
710such declarations have file scope regardless of the nesting of the
711declaration.
712Hiding file declarations in what appears to be a local
713scope is undesirable and will elicit complaints from a good compiler.
714.Pp
715Casts and
716.Ic sizeof Ns 's
717are not followed by a space.
718.Ic sizeof Ns 's
719are written with parenthesis always.
720The redundant parenthesis rules do not apply to
721.Fn sizeof var
722instances.
723.Pp
724.Dv NULL
725is the preferred null pointer constant.
726Use
727.Dv NULL
728instead of
729.Vt ( "type *" ) Ns 0
730or
731.Vt ( "type *" ) Ns Dv NULL
732in contexts where the compiler knows the
733type, e.g., in assignments.
734Use
735.Vt ( "type *" ) Ns Dv NULL
736in other contexts,
737in particular for all function args.
738(Casting is essential for
739variadic args and is necessary for other args if the function prototype
740might not be in scope.)
741Test pointers against
742.Dv NULL ,
743e.g., use:
744.Bd -literal
745(p = f()) == NULL
746.Ed
747.Pp
748not:
749.Bd -literal
750!(p = f())
751.Ed
752.Pp
753Do not use
754.Ic \&!
755for tests unless it is a boolean, e.g., use:
756.Bd -literal
757if (*p == '\e0')
758.Ed
759.Pp
760not:
761.Bd -literal
762if (!*p)
763.Ed
764.Pp
765Routines returning
766.Vt "void *"
767should not have their return values cast
768to any pointer type.
769.Pp
770Values in
771.Ic return
772statements should be enclosed in parentheses.
773.Pp
774Use
775.Xr err 3
776or
777.Xr warn 3 ,
778do not roll your own.
779.Bd -literal
780	if ((four = malloc(sizeof(struct foo))) == NULL)
781		err(1, (char *)NULL);
782	if ((six = (int *)overflow()) == NULL)
783		errx(1, "number overflowed");
784	return (eight);
785}
786.Ed
787.Pp
788When converting K&R style declarations to ANSI style, preserve
789any comments about parameters.
790.Pp
791Long parameter lists are wrapped with a normal four space indent.
792.Pp
793Variable numbers of arguments should look like this:
794.Bd -literal
795#include <stdarg.h>
796
797void
798vaf(const char *fmt, ...)
799{
800	va_list ap;
801
802	va_start(ap, fmt);
803	STUFF;
804	va_end(ap);
805	/* No return needed for void functions. */
806}
807
808static void
809usage(void)
810{
811	/* Optional blank line goes here. */
812.Ed
813.Pp
814Optionally, insert a blank line at the beginning of functions with no local
815variables.
816Older versions of this
817.Nm
818document required the blank line convention, so it is widely used in existing
819code.
820.Pp
821Do not insert a blank line at the beginning of functions with local variables.
822Instead, these should have local variable declarations first, followed by one
823blank line, followed by the first statement.
824.Pp
825Use
826.Xr printf 3 ,
827not
828.Xr fputs 3 ,
829.Xr puts 3 ,
830.Xr putchar 3 ,
831whatever; it is faster and usually cleaner, not
832to mention avoiding stupid bugs.
833.Pp
834Usage statements should look like the manual pages
835.Sx SYNOPSIS .
836The usage statement should be structured in the following order:
837.Bl -enum
838.It
839Options without operands come first,
840in alphabetical order,
841inside a single set of brackets
842.Ql ( \&[
843and
844.Ql \&] ) .
845.It
846Options with operands come next,
847also in alphabetical order,
848with each option and its argument inside its own pair of brackets.
849.It
850Required arguments
851(if any)
852are next,
853listed in the order they should be specified on the command line.
854.It
855Finally,
856any optional arguments should be listed,
857listed in the order they should be specified,
858and all inside brackets.
859.El
860.Pp
861A bar
862.Pq Ql \&|
863separates
864.Dq either-or
865options/arguments,
866and multiple options/arguments which are specified together are
867placed in a single set of brackets.
868.Bd -literal -offset 4n
869"usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en"
870"usage: f [-a | -b] [-c [-dEe] [-n number]]\en"
871.Ed
872.Bd -literal
873	(void)fprintf(stderr, "usage: f [-ab]\en");
874	exit(1);
875}
876.Ed
877.Pp
878Note that the manual page options description should list the options in
879pure alphabetical order.
880That is, without regard to whether an option takes arguments or not.
881The alphabetical ordering should take into account the case ordering
882shown above.
883.Pp
884New core kernel code should be reasonably compliant with the
885.Nm
886guides.
887The guidelines for third-party maintained modules and device drivers are more
888relaxed but at a minimum should be internally consistent with their style.
889.Pp
890Stylistic changes (including whitespace changes) are hard on the source
891repository and are to be avoided without good reason.
892Code that is approximately
893.Fx
894KNF
895.Nm
896compliant in the repository must not diverge from compliance.
897.Pp
898Whenever possible, code should be run through a code checker
899(e.g., various static analyzers or
900.Nm cc Fl Wall )
901and produce minimal warnings.
902.Pp
903New code should use
904.Fn _Static_assert
905instead of the older
906.Fn CTASSERT .
907.Sh FILES
908.Bl -tag -width indent
909.It Pa /usr/src/tools/build/checkstyle9.pl
910A script to check for violations of
911.Nm
912in a source file.
913.It Pa /usr/src/tools/tools/editing/freebsd.el
914An Emacs plugin to follow the
915.Fx
916.Nm
917indentation rules.
918.It Pa /usr/src/tools/tools/editing/freebsd.vim
919A Vim plugin to follow the
920.Fx
921.Nm
922indentation rules.
923.El
924.Sh SEE ALSO
925.Xr indent 1 ,
926.Xr err 3 ,
927.Xr warn 3 ,
928.Xr style.Makefile 5 ,
929.Xr style.mdoc 5 ,
930.Xr style.lua 9
931.Sh HISTORY
932This manual page is largely based on the
933.Pa src/admin/style/style
934file from the
935.Bx 4.4 Lite2
936release, with occasional updates to reflect the current practice and
937desire of the
938.Fx
939project.
940.Pa src/admin/style/style
941is a codification by the CSRG of the programming style of Ken Thompson and
942Dennis Ritchie in
943.At v6 .
944