Programming Style
Style Conventions
1. Names
A name should be informative, concise, memorable and preferably pronounceable.
- Use descriptive names for object labels of broader scope and short names
for objects of local scope
- Comment declared global variables, functions, classes and structures
- Use i, j, k, for loop indices, p, q for pointers, s, t for strings, m, n for integers.
- Use initial Capitalization for Globals; all capitals for CONSTANTS.
- Clarity is acheived via brevity.
- Be consistent by giving related (by similarity or contrast) objects related names.
- Use the context non-redundantly and use one term for one concept.
- Active verbs should be used to name functions because they will be doing something.
- Functions that return a boolean value should be named so that it reflects the true result.
- Make sure the implementation of your functions is accurate and that the name
reflects that.
2. Expressions and Statements
- Write them so that their meaning is self-evident.
- The goal is to write clear code, not clever code.
- Write the clearest code that does the job.
- Clarity is not the same as brevity.
- Use spaces around the operators for grouping purposes
- format to promote readability
- Indent to show structure.
- Use the natural form for expressions (as when you're saying them out loud)
- Use Parentheses to resolve ambiguity and show grouping
- When mixing unrelated operators, use parentheses.
- Logical operators bind tighter than assignment operators, so parentheses are mandatory here.
- Grouping the operands of higher precedence operators helps to see the expression
structure more clearly.
- Break up complex expressions
- Be careful with side effects (operators like ++ or -- return a value *and* modify a
variable);
3. Consistency and Idioms
- Use idioms for consistency
- Loop idioms:
for ( $i = 0; $i < n; $i++) {
$array[$i] = 1.0
} # loop control is in the for itself not the body
for (; ; ) {
... #event (infinite) loop
}
or
while (1) {
... #event (infinite) loop
}
- Use else-ifs for multi-way decisions
4. Magic Numbers
Magic numbers ("Metadata") are constants, array sizes, character positions,
conversion factors, and other literal numeric values that appear in programs.
- Give names to magic numbers. (To any number besides 0 or 1)
- Use character constants rather than integers; Use library functions or
character classes rather than character constants.
- Use the explicit representation of 'zero' (i.e. 0, \0, "", 0.0, (), <> ) for
integer 0, string terminator, null string, decimal 0, null list, null filehandle
- Use the language to calculate the size of an object: (i.e. length EXPR,
@array, %hash )
5. Comments
- Don't belabor the obvious. Comments should add something that is not
immediately evident from the code.
- Comments should collect into one place information that is spread through
the source code.
- Well chosen names which convey the information can substitute for comments.
- Comment functions and global data (variables, constant definitions, fields in
structures and classes)
- Helpful comments can cite references, describe data used, indicate algorithm
performance, and/or tell why and how an original algorithm was modified.
- Don't comment bad code; rewrite it. Clue: lines of code <= lines of comment
- Don't contradict the code. When fixing a bug, fix the comment about the bug too.
- Clarify, don't confuse.
Reference: Kernighan, Brian W, and Pike, Rob, The Practice of Programming,
Addison-Wesley, 1999
Questions about the questions? Send mail to Robert Katz: katz@cis.highline.ctc.edu
Last Update December 18, 1999