This document covers coding guidelines to use when writing C code. It is very much a WORK IN PROGRESS.
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 reigns supreme. Under no circumstances should the infinitely ugly GNU C style be used. Ever.
The ForgeRock C code style rules are based on the Coding Style and Guidelines except that I think we can safely ignore the 120 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.
- 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.
- 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.
- 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.
Consider the following example for a few of the points listed above:
should be written as:
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: