- Indent at least 3 spaces but not more than 8. This is enough to
stand out but not so much that code shifts wildly across the page.
- If your indenting is over 4 levels deep then make
the deeply indented code a procedure.
- Use blank lines between groups of lines of code that have a common
purpose. In every 10 or so lines of code there should be at least one
blank line form paragraphs of code. You would never write a book
without paragraphs, same for your code. Consider commenting in an
single line of informative text before each paragraph.
- Use at least two blank lines before a procedure so that the
procedures stand out.
- Put a comment block before every procedure even if it is only
a couple of lines.
- Always put a space after a comma. This makes lists much
more readable.
- Never write a procedure that is more than a page long.
- If procedure calls are of the form procname(args) then
there should be no space between the procname and the opening paren.
- If there is a keyword followed by an opening paren allowed in the
language then there should be a space between the keyword and the
paren as in: while (
- In C try to hide opening braces and expose closing braces.
if (test(y)) {
stmt1;
stmt2;
}
- else should begin a line. Never use the "elephant ears else":
if (test) {
dogs();
cats();
} else { // BAD elephant ears else
bats();
ants();
}
but rather:
if (test) {
dogs();
cats();
}
else { // OK
bats();
ants();
}
this makes the location of the else clear.
- An opening brace should always be preceeded by a blank.
- If you have a single statement after an if or looping construct
and you don't provide a separate block for it (such as using braces
in C++) then put the single line right after the if.
Not:
if (test)
x = func(y);
but rather clearly attach the code to the if or use braces:
if (test) x = func(y);
or
if (test) {
x = func(y);
}
You may violate this rule when one of the if clauses (then or else) has
a block in braces then both should have a block in braces.
Not:
if (test) x = func(y);
else {
cat();
dog();
}
but rather:
if (test) {
x = func(y);
}
else {
cat();
dog();
}
- Use meaningful variable names. Trivial counters, indexs in for
loops, and temporaries can optionally be single letters but the rest
should have meaning. Bad variable names include things like
var, thx1138, blah, and stuff.
Consider using "camel case" (mixed upper and lowercase) to make
readable variables: windVelocity or carsPerSecond.
Use simple variables such as x or v if the well
known or reference math equations use those specific variable names.
- Avoid mixing declarations and executable code in the middle of
blocks. Move declarations to the beginning of enclosing blocks when
possible. If this moves the declarations away from the scope of use
then create a block specifically for defining the scope of the
declarations. This makes the scope clear and the operations on the
variables uncluttered. (This is an often contested view and some
object operations require mixing of declarations and operations. But
decluttering the opertions with declarations I find refreshing. You
can make your own choice.)
- Whenever possible, initialize variables that are used in a loop
right before the loop. Separation of initialization of variables and
use of variables in a loop could be a source of future bugs and makes
the code less readable.
- Avoid just pasting duplicate code around in a program, when a
procedure can be created and duplicate code removed. Only do this if
it is logical.
- Apply these rules consistently throughout your program.
You lead a reader into your style. Don't change it on them midstream.
- Do not surprise the user with unexpected "cleverness", when you
can make your code say clearly what it is doing. This kind of
cleverness often leads to "clever" and hard to find bugs.