Style Guide

Variables

• variables should have scope as narrow as possible for how they are used
• communication between functions should be via parameters and return values rather than through global variables

Identifiers

• Identifiers should be lower case, with underscores between words in multi-word identifiers.
• Single-letter identifiers are unacceptable except for loop counters, when matching function prototypes to those in the documentation for similar functions, and when implementing an algorithm from reference material written using them.
• Constants defined with #define should be all upper case and with underscores to separate words.

Indentation and other Spacing

• The contents of a block should be indented further than the containing block. You may use whatever nonzero indentation you wish as long as you are consistent.
• Put a space between function arguments and around binary operators (so f(x + y, z), not f(x+y,z)). You may or may not include a space after and before parentheses as long as you are consistent in your choice (so f( x + y, z ) is acceptable, or even f ( x + y, z )).
• You may put the opening brace of a block at the end of the line or on its own line as long as you are consistent.
• The closing brace should be on its own line.
• Use at least one blank line between function definitions.
• Use blank lines with functions to group statements that work together to implement a single step of an algorithm.

Comments

• Each function declaration should be preceded by a comment describing
  • any preconditions (what needs to be true in order for the function to do what the comment claims it will do);
  • the postconditions (what it does, including effects on data pointed to by any pointer arguments and (when used properly) global variables, and the return value;
  • the caller's responsibility for releasing any dynamically allocated memory or other resources allocated by the function; and
  • the purpose of each argument.
• Within functions, comments should be used to indicate which lines of code implement which steps of an algorithm (so will roughly correspond to blank lines within a function) and invariants that are not obvious and are necessary for the subsequent code to be correct.