Style Guide
Identifiers
- Be consistent with formatting of 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.
Indentation and other Spacing
- (For languages that do not determine blocks based on indentation) 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 )
).
- Be consistent with placement of opening braces in languages
that require them. 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 accompanied 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
(in languages without garbage collection);
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.