Software Quality Guidelines

Prof. Arthur P. Goldberg

Spring, 2004
Owner: APG Version: 1.2 1/2004

 

These are some guidelines for writing good code. They are based on Tom Gelbs Software Inspection, 1993, pp. 423-427.

 

C1. Semantics The code should implement the specification, as defined in the assignment.

C2. Simplicity The code should accomplish its task (implement the semantics) as simply as possible, so it can be easily understood.

C3. Confined The code should confine itself to the semantics, and not implement other functionality.

C4. Perform The code should implement the specification with an efficient algorithm. The code should efficiently use memory.

C5. Robust The code should handle errors well. It should try to recover from system errors. Unrecoverable system errors and input errors should produce comprehensible error messages.

C6. Non-repetitive Basic concepts (in code or comments) should be stated only once. Subsequent use of the concept should refer to the initial statement.

C7. Well Commented Comments in the code should accurately, thoroughly, clearly and concisely describe the code.

C8. Layout The code layout (indentation, spacing, variable naming, etc.) should help make the code easy to understand.

C9. Symbolic The code should use symbolic constants, not hard-coded values.

C10. Resourceful The code should use data structures and algorithms available in the language or its libraries when appropriate.

C11. Tested The code should be thoroughly tested. Test cases should be packaged with the code.

Some Comments

Guidelines 1, 2, 3 and 11 are concerned with software correctness. If informal correctness proofs are appropriate, they should appear in the comments.

Guideline 4 is fairly vague, but difficult to make more precise. Id be interested in suggestions for improving it. Guideline 10 relates to 4, because reusing good code in libraries can help make efficient algorithms.

Guidelines 6 and 9 talk about non-redundant expression of ideas. Redundant ideas are bad because they must be modified in multiple places. This can be difficult or impossible when the multiple places become widely separated.