Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • 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:

...

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

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

...