== HelenOS C Coding Style Standard ==

Any source contribution to HelenOS must follow the C style rules described below.

=== 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 [http://en.wikipedia.org/wiki/Indent_style#K.26R_style 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 [wiki:BazaarCommitRules very similar rules]

=== 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 [wiki:CopyrightRules copyright rules].
 * Do **not** use Yoda comparisons (e.g. NULL == ptr)