Classes:

• Does the class interface present a consistent abstraction?
• Is the class well named? Does the name describe the central purpose of the class?
• Does the class's interface make it obvious how you should use the class?
• Is the class's interface abstract enough that you don't have to think about how it's underlying methods are implemented? Can you treat the class as a black box conceptually and in practice?

Routines: (Functions/Procedures/Methods)

• Does each routine's name describe exactly what the routine does?
• Does each routine perform one well-defined task?
• Have all parts of each routine that would benefit from being put into their own routines been put into their own routines?
• Is each routine's interface obvious and clear?

Data Names:

• Are type names descriptive enough to help document data declarations?
• Are variables named well?
• Are variables only used for the purpose for which they were originally named?
• Are loop counters given more informative names than i,j, and k?
• Are well-named enumerated types used instead of makeshift flags or boolean variables?
• Are named constants used instead of magic number literals or magic string literals?
• Do naming conventions distinguish among type names, enumerated types, named constants, local variables, class variables, and global variables?

Data Organization:

• Are extra variables used for clarity when needed?
• Are references to variables close together?
• Are data types simple so that they minimize complexity?
• Is complicated data accessed through abstract access routines (Abstract data types) instead of directly?

Control:

• Is the primary path throught the code clear?
• Are related statements grouped together?
• Have relatively independent groups of statements been packaged into their own routines?
• Does the normal case (most frequently executed) follow the +if_ rather than the else?
• Are control structures simple so that they minimize complexity?
• Does each loop perform one and only one function, as a well-defined routine should do if it replaced the loop?
• Is nesting minimized?
• Have boolean expressions been simplified by using additional boolean variables, boolean functions, and decision tables?

Layout:

• Does the program's layout show its underlying logical structure?

Design:

• Is the code straightforward? Is it easy to understand? Does it avoid clever programming tricks which mask the underlying algorithm?
• Does the code rely on language specific side-effects?
• Are implementation details hidden behind a well-defined class interface or routine call?
• Is the program written in terms of the actual problem domain as much as possible rather than in terms of computer-science or programming language structures?

• Can someone pick up the code and immediately start to understand it from just the comments?
• Do comments explain the code's intent or summarize what the code does rather than just repeating the code?
• Is the Psuedocode Programming Process used to reduce commenting time?
• Has tricky code been rewritten rather than commented?
• Are comments up to date?
• Are comments clear and correct?
• Does the comenting style allow comments to be easily modified?
• Before the code ships, have all marker comments been removed and properly dealt with?

Individual Line Statements and Paragraphs:

• Does the code avoid endline comments?
• Do comments focus on why rather than how?
• Do comments prepare the reader for the code to follow?
• Does every comment count? Have redundant, extraneous, and self-indulgent comments been removed or improved?
• Are surprises documented?
• Have abbreviations in comments been avoided?
• Is code that works around an error or undocumented features commented?

Data Declarations:

• Are units on data declarations commented?
• Are the ranges of values on numeric data commented?
• Are coded meanings commented?
• Are limitations on input data commented?
• Are flags documented to the bit level?
• Has each global variable been commented where it is declared?
• Has each global variable been identified as such at each usage, by a naming convention, a comment, or both?
• Are magic numbers replaced with named constants, enumerations, or varaibles rather than just documented?

Control Structures:

• Are comments inserted at their natural spots (control structures or at the beginning of long blocks of code)?
• Are the ends of long or complex control structures commented and/or when possible simplified to avoid the need for comments?

Routines:

• Is the purpose of each routine commented?
• Are other important facts about the routine given in comments, when relevant, including input and output data, interface assumptions, limitations, error corrections, global side-effects, and sources of algorithms?

Files, Classes, and Programs:

• Does the program have a short usage document?
• Does the program have a short design document?
• Is the purpose of each file described in a block header at the beginning of each file?
• Are the author's contact info included in the block header for each file?
• Does each class have a consistent commenting layout used throughout the interface?
• Do implementation details of the class remain hidden (IE not spelled out in the interface comments)?

-- ShawnDB - 16 Jun 2008
to top