Summary of Steve McConnell's Code Complete

(ISBN 1-55615-484-4)

Architecture

• Clearly specify requirements for inputs and outputs (accuracy, type, range, etc.)
• Check that the overall organization is clear (algo in Program Design Language, modules, flexibility, low complexity, open to changes, programming conventions, etc.)
• Make sure that debugging aids can be turned off easily in release version
• Debug until no warning shows up when compiling
• Implement error handling
• Deliver the core of the program in the first release, while planning for several releases
• If running behind, remove features instead of adding staff
• Use evolutionary delivery so as to always have a working product available ("Sync and stabilize"), and have the possiblity of taking advantage of unexpected opportunities
• Program in terms of the problem rather than the solution

Module

• Must have a central purpose, be used around a common set of data, have a cohesive set of services, be independent from other modules
• Only one module per source file

Routine

• Reasons to use routines: Reducing complexity, avoiding duplicate code, limiting effects of changes, hiding sequences/data structures/global data/pointer operations, promoting code reuse, isolating complex operations
• Use left-to-right order for input and output parameters
• Don't modify the contents of an input value
• Use meaningful names (eg. strInputBuffer, lOutputLong)
• Use all variables: If only some parameters in a structure are used, pass them as individual params

Data

• Establish consistent naming conventions
• Use descriptive names, with prefixes to indicate their type and scope
• Avoid redefining predefined type
• Initialize before use, and reset to NULL after use
• Use the smallest possible scope
• Avoid reusing variables
• If global variables must be used, access them through methods instead
• Avoid magic numbers
• Check pointers for validity before use
• Use methods to ease pointer manipulation

Conditionals

• IF-ELSE: Set the normal case to the IF block
• CASE: Do handle the default case
• FOR:
  • Init code just before the loop
  • Don't monkey with the loop index
  • Don't use the index later once the loop has ended
• GOTO
  • Only at last resort, to make code more readable
  • Only use one label per routine
  • Use GOTOs to go forward only
• Avoid deep-nested routines

Commenting

• Do explain the code, but don't repeat what it does
• Use Program Design Language to reduce commenting time
• Don't use endline comments
• Answer the why of the code rather than the how
• Put comments before the code they describe
• Do comment surprise code, or workarounds to known bugs