MirOS Manual: style(9)

STYLE(9)                      BSD Kernel Manual                       STYLE(9)

NAME

     style - BSD style guide for C source code

DESCRIPTION

     This manual page specifies the preferred style for C source files in the
     MirOS source tree. For historical reasons, it's still called "Kernel
     source file style guide (KNF)", although it has been applied to userland
     code for 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 pre-
     cedents 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.)
            * British spelling is preferred in general. Restrict yourself
            * to the CESU-8 (UTF-8) Unicode BMP subset or, preferably, the
            * ISO_646.irv:1991 7-bit character set (ANSI_X3.4-1968). Units
            * are metric and conform to the SI; use ISO/IEC 60027-2 binary
            * praefices for multiples of 1024 and SI praefices for 1000s.
            */

     Kernel include files (i.e., <sys/*.h>) come first; normally, you'll need
     either <sys/types.h> or <sys/param.h>, but not both! <sys/param.h> in-
     cludes <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 in-
     cludes, but after <sys/types.h>. Put non-local includes in brackets, lo-
     cal includes in double quotes.

           #include <sys/types.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, i.e.,
     <sys/param.h> and <sys/time.h> first, then all other system includes
     sorted, then machine and device includes sorted (if possible), then net-
     work includes sorted (if possible), then /usr/include files sorted, then
     local includes (also sorted if possible).

           #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 separated by another blank line from the file iden-
     tification 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 (this excludes most header files,
     although some use a technique to define their ID to a macro which is ex-
     panded by the main source file or somesuch) to use these macros; copy
     them over, the macros are safe to be used more than once in the same file
     in MirOS. Note that this may introduce CVS branch merge conflicts. These
     three macros are defined in <sys/cdefs.h>:

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

     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,
     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 should not be used in native MirOS code. Only
     write out prototypes with full variable names in manual pages; in all
     other files, prototypes should not have variable names associated with
     the types (this is what manpages are for); i.e., use:

           void function(int);
     not:
           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 a
     space.

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

           __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 *ambsntowcs(const char *, size_t)
               __attribute__((__nonnull__(1)))
               __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 only a 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,
     after the macro name or closing parentheses. 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 sup-
     plied 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 {
                   ONE,
                   TWO
           } et;

     When declaring variables in structures, declare them sorted by use, then
     by size (largest to smallest), then by alphabetical order. You may at-
     tempt 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 {
                   /* queue glue for foo lists */
                   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 the struct tag. Avoid
     typedefs ending in "_t", except as specified in Standard C or by POSIX,
     such as "uint32_t" (which requires <stdint.h>, or its superset
     <inttypes.h>). Don't use the same name for a struct tag and a typedef, as
     this makes the code unusable from C++.

           /* 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.
            */
           int
           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;
                           break;
                   case 'n':
                           num = strtonum(optarg, 0, INT_MAX, &errstr);
                           if (errstr) {
                                   warnx("number is %s: %s", errstr, optarg);
                                   usage();
                           }
                           break;
                   case '?':               /* redundant here but ok */
                   default:
                           usage();
                           /* 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 or 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. It helps when debugging (de-
     fine 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. Always document single-semicolon bodies with a com-
     ment; here, same line is ok.

           for (p = buf; *p != '\0'; ++p)
                   ;       /* nothing */
           while (/* CONSTCOND */ 1)       /* or: for (;;) */
                   stmt;
           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)
                           stmt;
           }

     Parts of a for loop may be left empty, although while loops are prefer-
     able especially in such cases. Don't put declarations inside blocks un-
     less the routine is unusually complicated.

           for (; cnt < 15; cnt++) {
                   stmt1;
                   stmt2;
           }

     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;

     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.

     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)
                   stmt;
           else if (bar != NULL) {
                   stmt;
                   stmt;
           } else
                   stmt;

     Avoid doing multiple assignments in one statement, like this:

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

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

     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)))
                   exit(error);

     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);
           k = !(l &
               FLAGS);

     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."
                    */
                   exit(0);
           }

     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 variables in functions, declare them sorted by size (larg-
     est to smallest), then in alphabetical order; multiple ones per line are
     okay. If a line overflows, reuse the type keyword. Declarations must fol-
     low ANSI X3.159-1989 ("ANSI C").

     Be careful not to obfuscate the code by initialising variables in the de-
     clarations. 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: ANSI C says that such
     declarations have file scope regardless of the nesting of the declara-
     tion.

     Note that indent(1) comes with a sample .indent.pro which understands
     most of these rules, starting from MirOS #9. As of MirOS #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. The excep-
     tion to this is in functions containing assembly code where the
     "register" specifier is required for proper code generation in the ab-
     sence of compiler optimisation.

     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, you must apply the "volatile" type-
     qualifier to the variable in question. Failure to do so may result in im-
     proper code generation when optimisation is enabled. Note that for
     pointers, the location of "volatile" specifies if the type-qualifier ap-
     plies to the pointer or the thing being pointed to. A volatile pointer is
     declared with an optional 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;

     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 set inside signal handlers should be of type "volatile
     sig_atomic_t" if possible. This guarantees that the variable may be ac-
     cessed 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 null pointer constant. Never use 0 in place of
     NULL. Use NULL instead of (type *)0 or (type *)NULL in all cases except
     for arguments to variadic functions where the compiler does not know the
     type.

     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')
     not
           if (p && !*p)

     Use <stdbool.h> for boolean values, not int.

     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)));

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

                   STUFF;

                   va_end(ap);

                   /* No return needed for void functions. */
           }

           static void
           usage(void)
           {
                   /* from crt0.o */
                   extern const char *__progname;

     Usage statements should take the same form as the synopsis in manual
     pages. Options without operands come first, in alphabetical order inside
     a single set of braces, followed by options with operands, in alphabeti-
     cal order, each in braces, 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 braces.

     If numbers are used as options, they should be placed first, as shown in
     the example below. Uppercase letters take precedence over lowercase. Note
     that the options list in manual pages should be purely alphabetical, ex-
     cept 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 __progname string may be used instead of hard-coding the program's
     name. It's better to place the extern declaration outside of the function
     body though, as it's file-global in ISO C either way, and that makes this
     fact more visible.

                   fprintf(stderr, "usage: %s [-ab]\n", __progname);
                   exit(1);
           }

     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 -W -Wpointer-arith -Wbad-function-cast ...", "make
     __CRAZY=Yes", lint(1) or splint from the ports tree) and produce minimal
     warnings. Try to write source code that will compile without any warn-
     ings, failures or malfunctions with gcc3 -Os -std=c99 -Wbounded, pcc -O,
     SUNWcc, and gcc4 -O2 -fwrapv -std=c99 -Wformat. Do try to keep code work-
     ing with gcc3 -std=c89, possibly with support for long long int.

     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 what is applicable from this guide, ex-
     cept that function declarations are all on one line; use Korn syntax
     throughoutly; never use the ` character; it is okay to use reasonably re-
     cent mksh(1) extensions. Do not use the typeset built-in command, always
     write local instead.

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

FILES

     /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.

SEE ALSO

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

HISTORY

     This man 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 MirOS source tree, in-
     cluding an improved Open Source licence.

MirOS BSD #10-current          February 9, 2014                              9

Generated on 2014-07-04 21:17:45 by $MirOS: src/scripts/roff2htm,v 1.79 2014/02/10 00:36:11 tg Exp $

These manual pages and other documentation are copyrighted by their respective writers; their source is available at our CVSweb, AnonCVS, and other mirrors. The rest is Copyright © 2002‒2014 The MirOS Project, Germany.
This product includes material provided by Thorsten Glaser.

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