This document covers coding guidelines to use when writing C code.
It is expected that code refactoring will follow this ForgeRock C coding standard, unless specific circumstances dictate how the code is to be formatted. Following the FR coding standard should guard against 'bit-rot' or source code unravelling.
All new source files must begin with the same copyright notice as recommended in the Coding Style and Guidelines
The ForgeRock C coding style
This style is mainly oriented around the desire to make C code more readable. Unless otherwise stated, the Kernighan and Ritchie style (otherwise known as "Egyptian Style") reigns supreme. This basically boils down to:
No other variations should be used, especially not the infinitely ugly GNU C style:
The ForgeRock C code style rules are based on the Coding Style and Guidelines except that I think we can safely ignore the 120 character column limit on line lengths - we have big screens.
- Source files MUST contain a valid copyright notice (see above).
- Source files MUST NOT contain tab characters - code MUST be formatted using 4 character space indents.
- Curly braces MUST ALWAYS be used with if, while, for and do/while and the opening brace must appear on the SAME LINE as the keyword EVEN IF there is only one statement in the loop body or "if" statement. This is one thing perl got right.
- Checking against NULL should ALWAYS be explicit rather than implied.
- Assignment of the null character (i.e. one byte) should always be done with '\0' as opposed to 0 (which has type int).
- Never declare more than one variable at a time, as this invites an opportunity to add a comment documenting the variable.
- When declaring pointers, the * should be moved towards the type rather than the variable.
- Macros must ALWAYS be defined in UPPERCASE.
- Always include system header files before local header files.
- Try to leave at least one blank line between declarations and code within a function, unless the function is particularly short.
- Document each and every function, giving its purpose, parameters and return value (for non void functions) just like Javadoc. Try to explain WHY the function does what it does, rather than just what it does.
- Document each and every macro, giving its purpose and parameters. More explanation is necessary with macros because there is no type information for the parameters.
- ALWAYS put spaces around binary operators, except for "->" and "."
- Do not put spaces around unary operators. sizeof is a unary operator.
- ALWAYS put space around the three parts of the conditional expression operator.
- ALWAYS separate function and macro parameters with a comma AND A SPACE.
- ALWAYS comment an intended fall through in a case statement.
- ALWAYS AVOID using variables l0 (lowercase-L-zero), l1 (lowercase-L-one), lO (lowercase-L-capital-O) etc. as these can easily be confused with the numeric constants 10, 11, etc.
- Variable names which are wordy and descriptive are ALWAYS TO BE PREFERRED to single or double letter variable names.
- Struct member names which are wordy and descriptive are ALWAYS TO BE PREFERRED to single or double letter member names.
- Single letter variable names should ONLY be used when the meaning is ABSOLUTELY OBVIOUS, e.g. "i" for an integer index is permissible. Such variables should have limited scope and not be used throughout lengthy functions.
- If you need a variable in which to store a function's result, PLEASE take a leaf out of Delphi's book and use result as opposed to anything else.
- ALWAYS comment #else and #endif (see "Preprocessor" below).
Consider the following example for a few of the points listed above:
should be written as:
A regrettable feature of the ISO C standard was that preprocessor constants are not allowed after #else and #endif. Things can quickly get confusing, for example:
Therefore #else and #endif should ALWAYS be commented as follows:
Use of the
defined operator should be considered over the #ifdef and #ifndef directives, because
defined allows for combinations. This gives a syntax error:
whereas this works as expected:
You could consider using Doxygen, http://www.stack.nl/~dimitri/doxygen/ which allows documentation to be generated from annotated source code, in which case the above would become a much more familiar: