Style Guide
Identifiers
- Identifiers should be lower case, with underscores between words
in multi-word identifiers.
- Single-letter identifiers are unacceptable except for loop counters
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.
- 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.