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