wiki:CStyle

Version 8 (modified by Jiri Svoboda, 10 years ago) ( diff )

Disclaimer

HelenOS C Coding Style Standard

Any source contribution to HelenOS must follow the C style rules described below. This list is, by definition, incomplete. Even if you comply with all the below rules does not mean nobody will comment on your C style. Do try to emulate the style of existing/surrounding code.

Source file encoding

  • Source files are encoded in UTF-8
  • Only ASCII subset should be used, except for cases of internationalized string literals
  • New lines are represented by the LF ('\n') character. Do not use CR + LF or CR.

Identifiers

  • C identifiers should be written in lower case, words separated by underscore "_" (foo_bar)
  • Types shall be suffixed with "_t"
  • Preprocesor symbols shall be all-upper case (FOO_MACRO(), FOO_CONSTANT)

Names

  • Use sensible, descriptive names.
  • Only use English names (English words, intelligible abbreviations)
  • Symbols with narrow scope (local variables) may have terse names (e.g. i)
  • Symbols with wide scope must have reasonably unique and meaningful names
  • Symbols with module scope or wider scope should follow the prefixing convention (e.g. fibril_create)

Indentation

  • Use a single Tab character for indentation, except for line continuations.
  • Tab width is considered to be 8 characters.
  • A line continuation is indented exactly 4 spaces.
  • Lines should not, in general, exceed 80 characters (tab counting as 8).
  • Each statement shall be placed on a line on its own.
  • Braces shall follow K&R Bracing Style
    • For functions the opening brace should be at a new line
    • In all other cases the opening brace should be at the same line as the previous token
  • Blocks within braces shall be indented 1 tab to the right as compared to the enclosing braces
  • Braces without any contents may be placed on the same line.
  • Blocks containing a single line can omit braces
    • For if…else statements both or neither of the T, F blocks must be delimited by braces
  • Labels in functions and switch statements are not indented (i.e. indented one less tab than the other contents of the block)

Spacing

  • All binary arithmetic, bitwise and assignment operators and the ternary conditional operator (?:) shall be surrounded by spaces
  • The comma operator shall be followed by a space but not preceded
  • All other operators shall not be used with spaces.
  • For functions and function-like operators there should be no extra spaces around or inside parentheses (int foo(void), sizeof(bar_t))
  • For control statements with parenteses there should be one space between the keyword and opening parenthesis (if (a == b))
  • Return statements should omit parentheses, especially when the argument is simple (return 1;)
  • Function-like operators (sizeof()) must never omit parentheses
  • There should be no space after asterisk (in type declarations or when dereferencing) (int *foo(int *f), *f = *g[3])

Blank lines

  • There should be newline at the end of every source file
  • There should be one blank line between any two top-level declarations that include a { } body - functions, enums, structs

Comments

  • In general, only /* */ comments are allowed. // comments can be used only to mark transitional code that needs further attention (e.g. // FIXME, // TODO, etc.).
  • Comments shall be written in gramatically correct English.
  • Comments describing action should be written in infinitive tense (/* Create a new entry on the stack. */)
  • Short comments need not be a complete sentence and need not end in '.' Such sentence fragments usually do not contain articles (/* Close callback connection */)
  • Multiline comments begin with "*" on each inner line.
  • The first line of a multiline comment must be just '/*' and the comment itself must start on the next line ('* Comment…')
  • Use Doxygen style comments for documenting functions.
  • All comments shall be placed above the line the comment describes, indented identically.
  • Every source file, function, type shall have a comment that describes its purpose.
  • Bazaar commit comments must follow very similar rules

Header files

  • Header guards should look like:
    • _LIBC_SYS_TIME_H for libraries
    • [LOCSRV_]CATEGORY_H for servers
    • SHEET_H for applications
  • Function declarations should be marked extern
  • Function declarations (same as forward static function declarations) should omit argument names
  • Preferred order of #include directives is angle-bracketed, then quoted
  • Second level of ordering is lexicographic
  • Give an honest attempt at IWYU (include what you use)
    • Each source module shall directly include the header file containing any symbol it uses
    • Except if there is an 'interface' header file that is meant to be included instead
    • Specifically, do not rely on an $include "common.h" to blanket-include all header files to all your source modules

License header and copyright messages

  • All newly created (original) HelenOS source files (.c and .h) should be licensed under the 3-clause BSD license in the form:
/*
 * Copyright (c) 2013 John Smith
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * - Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 * - The name of the author may not be used to endorse or promote products
 *   derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
  • Copyright lines should always be in the form
     * Copyright (c) <year> <Author's name>
    

Where <year> is the year the file was created by that person for new files. For modified files <year> is the year of last modification.

Miscellaneous

  • Spaces instead of tabs should be used for vertical spacing (not indentation). This enables the code to look consistent regardless of the tab size.
  • Copyright headers must follow the copyright rules.
  • Do not use Yoda comparisons (e.g. NULL == ptr)
Note: See TracWiki for help on using the wiki.