MirBSD manpage: style(9)

STYLE(9)                      BSD Kernel Manual                       STYLE(9)


     style - BSD style guide for (mostly C) source code


     This manual page specifies the preferred style for C source files in the
     MirBSD source tree. It used to be called "Kernel source file style guide
     (KNF)", although it applied to userland code since almost forever. These
     guidelines should be followed for all new code. In general, code can be
     considered "new code" when it makes up about 50% or more of the file(s)
     involved. This is enough to break precedent in the existing code and use
     the current style guidelines.

            * Style guide for the MirOS Project's Coding Styles.
            * Derived from the OpenBSD KNF (Kernel Normal Form).
            * indent(1) does not reformat this comment.

            * This is a documentation comment in doxygen format.
            * clang -Wcomment checks them for correct syntax.
            * Use only if you're honouring that standard.

            * VERY important single-line comments look like this.

           /* almost all small single-line comments look like this */

           /* A few others are sentences, thus end with a full stop. */

            * Multi-line comments look like this. Make them real sentences,
            * in contrast to single-line comments. Fill them so they look
            * like real paragraphs. indent(1) does reformat this comment.
            * (XXX: does it? It says slash+star+newline isn't reformatted.)
            * Encode files as ISO_646.irv:1991 7-bit character set ("ASCII")
            * or UTF-8 with codepoints from the UCS BMP only. Use traditional
            * German, Latin, British English (adapted for ICT), metric and SI
            * units and prefixes preferring ISO/IEC 60027-2 binary praefices.

     Kernel include files (i.e. <sys/*.h>) come first. You usually need either
     <sys/types.h> or <sys/param.h> but not both: BSD <sys/param.h> includes
     <sys/types.h>, which in turn includes <sys/cdefs.h>, and it's okay to
     depend on that. Also, add <sys/time.h> before the other system includes,
     but after <sys/types.h>. Put non-local includes in angle brackets, local
     includes in double quotes.

           #include <sys/types.h>
           #include <sys/time.h>
           #include <sys/ioctl.h>

     Machine and device includes follow. If it's a networked program, put the
     network include files next.

           #include <net/if.h>
           #include <net/if_dl.h>
           #include <net/route.h>
           #include <netinet/in.h>
           #include <protocols/rwhod.h>

     Then there's an optional blank line, followed by the other files from
     /usr/include. The list of include files should be sorted by group and, if
     possible, within the group. That is, <sys/param.h> and <sys/time.h>
     first, then all other system includes, then machine and device includes,
     then network includes, then /usr/include files, then local includes.

           #include <stdio.h>

     Global pathnames are defined in <paths.h>. Pathnames local to the program
     go in "pathnames.h" in the local directory.

           #include <paths.h>

     Then there's a mandatory blank line, and the user include files.

           #include "pathnames.h"

     The includes block is followed by another blank line to separate it from
     the file identification block. Add the CVS (or RCS) ID(s) of the file
     and, if taking over old source code, the SCCS ID and __COPYRIGHT as well;
     place another blank line after that. It is discouraged listing RCS IDs as
     comments at the beginning of files if it's possible to use these macros;
     copy them over (nore this may introduce CVS branch merge conflicts), the
     macros in MirBSD are safe to be used more than once in the same file.
     This used to exclude most header files; some worked around this defining
     a macro with their ID which would be expanded by the main source file,
     but if <sys/cdefs.h> can be relied on to have been included first or is
     included by the header file itself, there's no argument against using
     these macros in MirBSD. These four macros are defined in <sys/cdefs.h>:

           __COPYRIGHT("Copyright (c) 1989, 1993\n\
                   The Regents [...] reserved.");
           __SCCSID("@(#)cat.c     8.2 (Berkeley) 4/27/95");
           __RCSID("$MirOS: src/bin/cat/cat.c,v [...] Exp $");
           __IDSTRING(someotherid, "bla");

     All functions are prototyped somewhere.

     Function prototypes for private functions (i.e. functions not used else-
     where) go at the top of the first source module. In userland, functions
     local to one source module should be declared 'static'. This should not
     be done in kernel land since it makes it almost impossible to use the
     kernel debugger.

     Functions used from other parts of the kernel are prototyped in the
     relevant include file. It is strongly recommended that include files do
     not include other header files. Document interdependencies in the
     relevant manual pages.

     Functions that are used locally in more than one module go into a
     separate header file, e.g. "extern.h". This file is allowed to precede
     the, otherwise sorted, list of local include files. Do not use the same
     names as other well-known header files, such as these in /usr/include,
     these used by library dependencies or part of other applications that are
     often pulled in by the make(1) ".PATH" command.

     Use of the __P macro has been deprecated. It is allowed in code imported
     from other sources but not to be used in native MirBSD code. Only write
     out prototypes with full variable names in manual pages; in all other
     files, prototypes for documented functions should not have variable names
     associated with the types (this is what manpages are for); i.e. use:

           void function(int);
           void function(int a);

     Lining up prototypes after type names is discouraged because it is hard
     to maintain; use a single space. If lining up (existing code), prototypes
     may have an extra space after a tabulator to enable function names to
     line up:

           static char     *function(int, const char *);
           static void      usage(void);

     Function or macro names and their argument list are never separated by
     whitespace, only keywords that are not function-like (GCC attributes,
     sizeof, etc.) use a single space.

     Use __dead from <sys/cdefs.h> for functions that don't return:

           __dead void abort(void);
           void usage(int) __dead;

     Use GCC attributes extensively to catch programming errors, e.g.

           /* one line per function attribute */
           wchar_t *xambsntowcs(const char *, size_t)
               __attribute__((__bounded__(__string__, 1, 2)));
           /* use of an argument mandated by function pointer API */
           static int x_del_char(int __unused);
           /* macro evaluating its argument twice */
           #define DOUBLE(x) __extension__({               \
                   __typeof__(x) DOUBLE_x = (x);           \
                   (DOUBLE_x + DOUBLE_x);                  \

     In header files, put function prototypes within matching pairs of
     __BEGIN_DECLS / __END_DECLS. This makes the header file usable from
     languages like C++.

     Labels start at the second column, i.e. are prefixed with exactly one
     single space (ASCII 20 hex) character, no matter which block they are in.

     Macros are capitalised and parenthesised and should avoid side-effects.
     If they are an inline expansion of a function, the function is defined
     all in lowercase; the macro has the same name all in uppercase. In rare
     cases, function-like macros that evaluate their arguments only once are
     allowed to be treated like real functions and use lowercase. If the macro
     needs more than a single line, use braces. Right-justify the backslashes,
     as the resulting definition is easier to read. Use a single space after
     the #define cpp(1) command and, except if lining up single-line macros
     with tabstops, after the macro name or closing parentheses. In contrast
     to functions and invocations, the list of parameters omits the space
     after a comma separating parameters in macro definitions. If the macro
     encapsulates a compound statement, enclose it in a "do" loop, so that it
     can safely be used in "if" statements, like shown below. Do not forget
     the CONSTCOND lint(1) command. Any final statement-terminating semicolon
     shall be supplied by the macro invocation rather than the macro, to make
     parsing easier for pretty-printers and editors.

           #define MACRO(x,y) do {                                         \
                   variable = (x) + (y);                                   \
                   (y) += 2;                                               \
           } while (/* CONSTCOND */ 0)

     Enumeration values are all uppercase.

           enum enumtype {
           } et;

     When declaring variables in structures, generally declare them sorted by
     use, then by size (largest to smallest), then by alphabetical order. You
     may attempt to optimise for structure padding to avoid wasting space. The
     first category normally doesn't apply, but there are exceptions. Each one
     gets its own line. It is strongly recommended to not line them up either.
     Use single spaces, but line up the comments if desirable or, better,
     place them on their own lines just before the item they apply to.

     Major structures should be declared at the top of the file in which they
     are used, or in separate header files if they are used in multiple source
     files. Use of the structures should be by separate declarations and
     should be "extern" if they are declared in a header file.

           struct foo {
                   struct foo *next;       /* list of active foo */
                   struct mumble amumble;  /* comment for mumble */
                   int bar;
           struct foo *foohead;            /* head of global foo list */

     Use queue(3) and tree(3) macros rather than rolling your own lists when-
     ever possible. Thus, the previous example would be better written:

           #include <sys/queue.h>

           struct foo {
                   /* foo list queue glue */
                   LIST_ENTRY(foo) link;
                   /* comment for mumble */
                   struct mumble amumble;
                   int bar;
           /* head of global foo list */
           LIST_HEAD(, foo) foohead;

     Avoid using typedefs for structure types. This makes it impossible for
     applications to use pointers to such a structure opaquely, which is both
     possible and beneficial when using an ordinary struct tag. When conven-
     tion requires a typedef, make its name match, but not exactly identical
     to (which makes the code unusable from C++) the struct tag. Avoid
     typedefs ending in "_t", except as specified in Standard C or by POSIX.

           /* make the structure name match the typedef */
           typedef struct _bar {
                   int level;
           } BAR;

            * All major routines should have a comment briefly describing
            * what they do. The comment before the "main" routine should
            * describe what the program does.
           main(int argc, char *argv[])
                   int aflag, bflag, ch, num;
                   const char *errstr;

     For consistency, getopt(3) should be used to parse options. Options
     should be sorted in the manual page SYNOPSIS and DESCRIPTION, any usage()
     or similar function, the getopt(3) call and the switch statement, unless
     parts of the switch cascade. Elements in a switch statement that cascade
     should have a FALLTHROUGH comment. Numerical arguments should be checked
     for accuracy. Code that cannot be reached should have a NOTREACHED com-
     ment. The CONSTCOND, FALLTHROUGH, and NOTREACHED comments benefit lint.

           while ((ch = getopt(argc, argv, "abn:")) != -1)
                   switch (ch) {           /* indent the switch */
                   case 'a':               /* don't indent the case */
                           aflag = 1;
                           /* FALLTHROUGH */
                   case 'b':
                           bflag = 1;
                   case 'n':
                           num = strtonum(optarg, 0, INT_MAX, &errstr);
                           if (errstr) {
                                   warnx("number is %s: %s", errstr, optarg);
                   case '?':               /* redundant here but ok */
                           /* NOTREACHED */
           argc -= optind;
           argv += optind;

     Cast expressions and the value to be casted are never separated by a
     space; use parentheses about the latter if it's a compound expression.
     Use a space after keywords (if, while, for, return, switch) but not unary
     operators like sizeof, typeof, alignof, or function-like constructs like
     GCC attributes (see above). It is recommended to put parentheses around
     the return argument as well, although this is not a strict requirement,
     to accommodate languages such as C++ and PHP in which the result type
     differs when surrounded by parentheses. It helps when debugging (define
     return to a debug expression) though, except for void functions.

     No braces are used for control statements with zero or only a single
     statement, unless that statement is more than a single line (in which
     case they are permitted), it contains a comment (in which case they are
     recommended), or it contains a label (in which case they are mandated). A
     separate project may choose to mandate braces for all cases. Avoid empty
     bodies; otherwise, push the semicolon to the next line and indent it, and
     comment it (here, a same-line comment is permitted), or perhaps insert a
     redundant continue statement; never place the semicolon on the same line
     as the loop, and don't use empty braces except if absolutely required
     (e.g. the NXC compiler fails at loops with a sole semicolon as body), in
     which case they must not have any whitespace between the opening and
     closing brace and follow the loop statement on the same line, separated
     by one space.

           for (p = buf; *p != '\0'; ++p)
                   ;       /* nothing */           // traditional style
           for (p = buf; *p != '\0'; ++p)
                   /* nothing */;                  // less legible
           for (p = buf; *p != '\0'; ++p)
                   continue;       /* empty */     // optional; add a comment!

           while (/* CONSTCOND */ 1)       /* or: for (;;) */
           while (/* CONSTCOND */ 1) {
                   z = a + really + long + statement + that + needs +
                       two + lines + gets + indented + four + spaces +
                       on + the + second + and + subsequent + lines;
           while (/* CONSTCOND */ 1) {
                   if (cond)
           if (cond) {
                   /* comment */

     Parts of a for loop head may be left empty, although while loops are
     preferable especially in such cases. Don't put declarations inside blocks
     unless the routine is unusually complicated.

           for (; cnt < 15; cnt++) {

     Indentation is an 8 character tab. Second level indents are four spaces.

           while (cnt < 20)
                   z = a + really + long + statement + that + needs +
                       two + lines + gets + indented + four + spaces +
                       on + the + second + and + subsequent + lines;

     This is true for almost all languages but not HTML or XHTML (it is valid
     for XML, though xmlstarlet fo does not wrap at all). In assembly source
     code, labels always begin at the first column, and the comma separating
     operands is normally unspaced:

           /* ... */
                   xor     eax,eax
                   dec     ebx
                   jnz     1f
                   dec     eax
           1:      ret

     In assembly for processors that have it, do indent the branch delay slot,
     whether cancelled (,a on SPARC) or not (this rare example uses spaces):

                   cmp     %o2, BCOPY_SMALL
                   bge,a   Lbcopy_fancy    /* if >= this many, go be fancy */
                    btst   7, %o0          /* (part of being fancy) */

                   /* not much to copy, just do one byte at a time */
                   deccc   %o2
           /* ... */

     Do not add whitespace at the end of a line, and only use tabs followed by
     spaces to form the indentation. Never use more spaces than a tab will
     produce and do not use spaces in front of tabs. vim users are required to
     put "let c_space_errors = 1" into their ~/.vimrc. Fixup with ^K] in jupp.

     Closing and opening braces go on the same line as the else. Braces that
     aren't necessary may be left out, unless they cause a compiler warning.

           if (test)
           else if (bar != NULL) {
           } else

     Avoid doing multiple assignments in one statement, like this:

           /* bad example */
           if (foo) {
           } else if (bad)
                   *wp++ = QCHAR, *wp++ = c;

           /* write this as */
           if (foo) {
           } else if (good) {
                   *wp++ = QCHAR;
                   *wp++ = c;
           } else

     Do not use spaces after function names. Commas have a space after them.
     Do not use spaces after '(' or '[' or preceding ']' or ')' characters.

           if ((error = function(a1, a2)))

     Use positive error codes. Negative errors (except -1) are something only
     the Other OS does.

     Unary operators don't require spaces; binary operators do. Don't use
     parentheses unless they're required for precedence, the statement is
     confusing without them, or the compiler generates a warning without them.
     Remember that other people may be confused more easily than you. Do YOU
     understand the following?

           a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1;
           k = !(l & FLAGS);

     It's much better to break after an operator if you need to apply line
     breaks. This is especially true for shell scripts. The above example
     could be rewritten as:

           a = (((b->c[0] + ~d) == (e || f)) || (g && h)) ?
               i : (j >> 1);

     Lines ought to be not larger than 80 characters. Stick to 75 characters
     or less if possible, but in some cases it's ok to put a character in the
     80th column. Descriptions should not be longer than 66 characters, eMails
     must not be longer then 72 characters per line. In object-oriented
     languages, it may be acceptable to use up to 100 characters per line.

     Exits and returns should be 0 on success, and non-zero for errors.

                    * avoid obvious comments such as
                    * "Exit 0 on success."

     The function type should be on a line by itself preceding the function.
     This eases searching for a function implementation:

     $ grep -r '^function' .

           static char *
           function(int a1, int a2, float fl, int a4)

     When declaring local variables in functions, declare them sorted by size
     (largest to smallest), then in alphabetical order; multiple ones per line
     are okay. If a line overflows, restate the type keyword. Declarations
     should follow ANSI X3.159-1989 ("ANSI C89"). Be careful not to obfuscate
     the code by initialising variables in the declarations. Use this feature
     only thoughtfully. DO NOT use function calls in initialisers!

           struct foo one, *two;
           double three;
           int *four, five;
           char *six, seven, eight, nine, ten, eleven, twelve;

           four = myfunction();

     Do not declare functions inside other functions: such declarations have
     file scope regardless of the nesting of the declaration.

     Note that indent(1) comes with a sample .indent.pro which understands
     most of these rules, starting from MirBSD #9. As of MirBSD #11, it will
     also be installed into the user home skeleton directory.

     Use of the 'register' specifier is discouraged in new code. Optimising
     compilers such as GCC can generally do a better job of choosing which
     variables to place in registers to improve code performance. Functions
     containing assembly code where explicit register placement is required
     for proper code generation in the absence of compiler optimisation are
     excepted from this rule.

     When using longjmp() or vfork() in a program, the -Wextra or -Wall flag
     should be used to verify that the compiler does not generate warnings
     such as

           warning: variable `foo' might be clobbered by `longjmp' or `vfork'.

     If any warnings of this type occur, apply the "volatile" type-qualifier
     to the variable in question. Failure to do so will result in improper
     code generation when optimisation is enabled. Note that for pointers, the
     location of "volatile" specifies whether the type-qualifier applies to
     the pointer or the thing being pointed to. A volatile pointer is declared
     with an extra space and "volatile" to the right of the "*". Example:

           char * volatile foo;

     says that "foo" is volatile, but "*foo" is not. To make "*foo" (the thing
     being pointed to) volatile use the syntax

           volatile char *foo;

     and if both the pointer and the thing pointed to are volatile use:

           volatile char * volatile foo;

     "const" is also a type-qualifier and the same rules apply. Assume string
     literals are constant. Never make use of broken C APIs such as strchr(3)
     to "cast away" the "const" qualifiers. The description of a read-only
     hardware register might look something like:

           const volatile char *reg;

     Global flags accessed inside signal handlers should be of type "volatile
     sig_atomic_t" if at all possible. This guarantees that the variable may
     be accessed as an atomic entity, even when a signal has been delivered.
     Global variables of other types (such as structures) are not guaranteed
     to have consistent values when accessed via a signal handler.

     NULL is the preferred nil pointer constant. Never use 0 in place of NULL.
     Use NULL instead of (type *)0 or (type *)NULL in all cases except for
     (sentinel) arguments to variadic functions where the compiler does not
     know the type as some systems define NULL to 0 not "(void *)0UL".

     Don't use '!' for tests unless it's a boolean (or an integral flag used
     in a boolean context, almost certainly with a bitwise AND operation,
     since otherwise using a bool would be correct), i.e. use

           if (p != NULL && *p == '\0')
           if (p && !*p)

     Routines returning void * should not have their return values cast to any
     pointer type. Functions used as procedures should not have their return
     value explicitly cast to void, either. The exception are function-like
     macros like sigaddset(3), where failure to do so may result in compiler
     warnings about unused LHS in comma operations.

     You can assume that pointers to variables and function pointers share the
     same address space and have the same size as ptrdiff_t.

     Use err(3) or warn(3), don't roll your own!

                   if ((four = malloc(sizeof(struct foo))) == NULL)
                           err(1, NULL);
                   if ((six = (int *)overflow()) == NULL)
                           errx(1, "Number overflowed.");
                   return (eight);

     Old-style function declarations looked like this:

           static char *
           function(a1, a2, fl, a4)
               int a1, a2; /* declare ints, too, don't default them */
               float fl;   /* beware double vs. float prototype differences */
               int a4;     /* list in order declared */

     You really ought to replace them with ANSI C function declarations. Long
     parameter lists are wrapped with a normal four space indent.

     Variable numbers of arguments should look like this:

           #include <stdarg.h>

           void vaf(const char *fmt, ...)
                   __attribute__((__format__(__printf__, 1, 2)));

           vaf(const char *fmt, ...)
                   va_list ap;
                   va_start(ap, fmt);



                   /* No return needed for void functions. */

           static void

     Usage statements should take the same form as the synopsis in mdoc(7)
     manual pages. Options without operands come first, in case-insensitive
     (uppercase first) alphabetical order inside a single set of brackets,
     followed by options with operands in case-insensitive (uppercase first)
     alphabetical order, each in brackets, followed by required arguments in
     the order they are specified, followed by optional arguments in the order
     they are specified. A bar ('|') separates either-or options/arguments,
     and multiple options/arguments which are specified together are placed in
     a single set of brackets.

     If numbers are used as options, they should be placed first, as shown in
     the example below. Note that the options list ordering should be purely
     alphabetical, except that the no-argument options are listed first.

           "usage: f [-12aDde] [-b barg] [-m marg] req1 req2 [opt1 [opt2]]\n"
           "usage: f [-a | -b] [-c [-de] [-n number]]\n"

     The getprogname(3) function may be used instead of hard-coding the
     program's name.

                   fprintf(stderr, "usage: %s [-ab]\n", getprogname());

     New core kernel code should be reasonably compliant with the style
     guides. The guidelines for third-party maintained modules and device
     drivers are more relaxed but at a minimum should be internally consistent
     with their style; the current MirPorts Framework package tools are a bad
     example of style inconsistency (such as three different indentation
     styles: three spaces, four spaces and KNF one tab) and a good example of
     why it must be prevented.

     Whenever possible, code should be run through at least one code checker
     (e.g. "gcc -Wall -Wextra -Wpointer-arith -Wbad-function-cast ...", "make
     __CRAZY=Yes", lint(1) or splint from the ports tree) and produce minimal
     warnings. Write source code that compiles without any warnings, failures
     or malfunctions with gcc3 -Os -std=c99 -Wbounded -Wformat (or -std=c89),
     pcc -O and gcc4 -O2 -fwrapv -std=c99 -Wformat. Try to keep code working
     with gcc3 -std=c89 or at least both of -std=c99 and -std=gnu89.

     When rolling your own bools, use German names: Wahr, Ja, Nee, isWahr()
     ("is" + lcase is reserved) Otherwise the code might not compile any more
     past some point because some subsequent edition of ISO C made your type
     and constant definitions UB because suddenly the chosen English names are
     become keywords. This also applies to other framework-ish inventions.

     Note that documentation follows its own style guide, as documented in
     mdoc.samples(7). This however does not invalidate the hints given in this
     guide. Shell scripts also follow this guide as far as applicable, except
     function declarations are all on one line; never use the "`" character.
     Use Korn syntax and reasonably recent mksh(1) extensions.

           function bla {
                   (( x )) && foo=abcdefghijklmnopqrstuvwxyz$(fnord \
                   [[ $foo = @([a-z_]*([a-z0-9_]) ]] || exit 1


     /usr/share/misc/licence.template   Licence preferred for new code.

     ~/.indent.pro should contain at least the following items:

     -c0 -ci4 -di0 -nbs -ncsp -nfc1 -nlp -nlpi -Tbool -Tint16_t -Tint32_t
     -Tint64_t -Tint8_t -Tintmax_t -Tintptr_t -Tmbstate_t -Toff_t -Tptrdiff_t
     -Tsize_t -Tssize_t -Ttime_t -Tuint16_t -Tuint32_t -Tuint64_t -Tuint8_t
     -Tuintmax_t -Tuintptr_t -Twchar_t -Twint_t and a bunch of others. Note
     that the -c0 option might be problematic for existing code and may be
     better left out. mircvs://src/usr.bin/indent/.indent.pro contains a more
     complete list; even then, indent(1) does only basic help to apply KNF.


     indent(1), lint(1), err(3), queue(3), warn(3), mdoc.samples(7)


     This manual page is largely based on the src/admin/style/style file from
     the BSD 4.4-Lite2 release, with updates to reflect the current practice
     and desire first of the OpenBSD project, then for the MirBSD source tree,
     including an improved Open Source licence.

MirBSD #10-current            February 19, 2022                             10

Generated on 2022-12-24 01:00:14 by $MirOS: src/scripts/roff2htm,v 1.113 2022/12/21 23:14:31 tg Exp $ — This product includes material provided by mirabilos.

These manual pages and other documentation are copyrighted by their respective writers; their sources are available at the project’s CVSweb, AnonCVS and other mirrors. The rest is Copyright © 2002–2022 MirBSD.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.

Kontakt / Impressum & Datenschutzerklärung