Software Quality Inspection Checklist for Java Classes

This checklist is intended to be used with Report of Findings for inspecting and reporting on Java class definitions.  It is organized by software quality Criteria, according to the McCall model.

In the checklist, examples are given: they are not meant to be prescriptive, only suggestive.

Inspection Instructions

1. Familiarize yourself with the code you are to inspect.  Make sure you understand generally how it is designed to work, and that there are no passages of Java code which you do not recognize or understand at all.  If necessary, consult a Java manual.
2. Inspect the code for each checklist item in each category.
3. For a checklist item which requires code elements to have a certain property (e.g. layout used consistently, algorithms to be space efficient), make an entry in the Report of Findings if you discover an element which doesn't have the property.  Indicate where in the project (by line number and class name) you found the element.
4. For a checklist item which prohibits a code element (e.g. calls to System.exit), make an entry in the Report of Findings if you discover the element.  Indicate where in the project you found it.
5. For a checklist item which requires a code element to be present (e.g. a method with a particular name), make an entry in the Report of Findings if you discover that the element is absent.  Indicate the class or method header (by line number) in which the element ought to have appeared.

Quality Criteria and Inspection Items.

1. Consistency (of layout, name choice, and code organization)
1. Placement of braces ({ and }) done consistently throughout.
2. Indentation is used, consistently, to indicate block structure within braces.
3. Block comments precede the code they describe.
4. The same names or abbreviations are used consistently for the same concept (e.g. not next, nextNode, and nxtn in three places in the same class).
5. Naming conventions for classes, class members (methods and variables), constants, and local variables, are distinct and consistent (e.g.ClassName, classMethod, CLASS_CONSTANT, and local_variable).
2. Anomaly Management (of inputs and contexts which the requirements didn't anticipate)
1. Input parameters to public methods, and inputs read from files, are checked explicitly for all unacceptable values.
2. Unacceptable public input produces error output and/or throws exceptions.
3. Unacceptable public input produces a documented result (e.g. zero, null, the empty String ...) when there is no exception thrown.
4. Input parameters to private methods are assumed acceptable and are not checked.
3. Efficient Processing (using as little processing time as is reasonable)
1. Loops contain complex code, or other loops, only when necessary.
2. Array processing (especially search) contains loop exit code to execute when the condition is found.
4. Efficient Storage
1. All local and instance variables are actually used somewhere.
5. Simplicity
1. No method is longer than one page (about 60 lines including comments).
2. Math expressions, control expressions (in ifs, whiles, fors, and switches) are as simple as possible.
3. Little private methods are preferred to repeating the same code over and over in different places.
6. Self-Description
1. Comments are provided whenever the purpose or reason for doing something in the code is obscure.
2. Comments are provided to describe every method, however briefly.
3. Comments are provided to describe the purpose, restrictions, and relationships between all instance variables in a class.
4. All names are chosen well and consistently to reflect their usage and purpose.
5. Constants (static final) are used instead of magic numbers. (e.g. Don't write 42, write static final ULT_ANS = 42; and then use ULT_ANS instead.)
6. Booleans are not compared to boolean constants. (e.g. if (!found) is preferred to if (found == false)).
7. Modularity
1. Instance variables are not public.
2. Variables are declared as locally as possible.
3. Public method headers don't reveal the internal design of the class.
4. System.exit is not called directly.
8. Instrumentation
1. Every class has a parameterless toString method which returns a String containing a dump or summary of an instance of the class.