Task: Code Inspection

What is code inspection?

"Creating software is a highly inividualistic intellectual activity. Each software component is typically the work of one person or of a small team."
A. Frank Ackerman, Lynne S. Buchwald, Frank H. Lewski, 1989.

Code inspection, in its simpelest form, means that source code is inspected by other developers. It tries to solve the software problems that arrise due to the individualistic nature of the software development process.

How does it work?

If one of the developers finishes a class or class-member he/she should notify this on the maillist wcs-jabe-general. At least two other developers should inspect the code and post al remarks on the maillist. Follow-up actions will be discussed there.

Of course the code was most probably written with some mind-set. So things that seem strange may in fact be thouroughly thought over. Therefore I suggest that you communicate your remarks in small pieces to prevent you from writing a long story just to learn afterwards that things have been done for a certain purpose and can not be changed.

What is there to inspect?

There is a long list of checks that can be performed on a piece of source-code. First of all the following aspects should be considered per function or class-method:

  1. Coding technique
    1. Is the code written in a readable form?
    2. Is there sufficient comments to clarify the code?
    3. Are all algorithms in the code clear?
    4. Are the methods generic enough to be usable in all kinds of situations?
    5. Are methods not to long (in lines of code)?
  2. Completeness
    1. What is the range of input parameters?
    2. Are there any timing constraints on the inputs?
    3. Are all types of output clearly defined?
    4. What is the total output space?
    5. Are there any timing constraints on the outputs?
    6. Is there an output defined for each input?
    7. Are initial states identified?
    8. Is the invocation mechanism clear?
    9. Are all environmental constraints clear?
    10. Are sample input/output sets provided (if necessary)?
    11. Are all performance requirements clear?
    12. Should reliability requirements be specified?
    13. Is an operational profile specified (if needed)?
  3. Ambiguity
    1. Are all special terms clearly defined?
    2. Are the requirements interpretable in just one way?
    3. Is the input to output mapping clear in al cases?
  4. Consistency
    1. Are there no conflicts between requirements?
    2. Are there no two or more input states that map to one single output state?
    3. Are all quantitative units consistent?

Besides these checks on the function level, the following should be checked for each class:

  1. Completeness
    1. Are all source files and include files identified?
    2. Does the set of interface functions seem complete?
    3. Does the list of attributs seem complete?
    4. Is a test program available?
    5. Is source documentation available or can it be generated from the source?
  2. Ambiguity
    1. Should specified methods be placed in the parent class?
    2. Should specified methods be placed in a child class?
    3. Should specified attributes be placed in the parent class?
    4. Should specified attributes be placed in the child class?
    5. Is the inheritance structure (parent, child) clear?
  3. Consistency
    1. Is there a clear distinction between interface, constructors, operators and methods?
    2. Should methods be specified as "inline"?