Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

Overview

This document covers coding guidelines to use when writing C code.  It is very much a WORK IN PROGRESS.

Copyright notices

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.

Summary

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

Details

Consider the following example for a few of the points listed above:

Bad
int my_func(int *p,int c) {
	unsigned int *index = p + c - 1, entry_index=0;
	if (index) *index=entry_index;
}

should be written as:

Good
/******************************************************************************************
 * The function my_func divides by the number you first thought of, which is useful when
 * parsing HTTP header information.
 * Parameters:
 *    int_base is a pointer to a block of memory containing a series of signed integers
 *    count is the number of signed integers in the block pointed to by "int_base"
 * Return:
 *    If successful, the function returns 1, if unsuccessful, the function returns 0
 ******************************************************************************************/
int my_func(int* int_base, int count) {
	unsigned int*  index = int_base + count - 1;
	unsigned int   entry_index = 0;

	if (index != NULL) {
    	*index = entry_index;
	}
    entry_index = sizeof(int);
    // etc. etc.
}

 

 

 

  • No labels