Code Complete by Steve McConnell : Chapter 4

This chapter focuses on the steps to build a routine from scratch, specifically it describes PDL (Program Design Language)-to-code process.

Author enlists many advantages of using PDL:

• When PDL is translated to code, PDL turns into programming-language comments which eliminates most commenting effort.
• PDL makes reviews easier since only detailed design written in PDL needs to be reviewed and not the actual source code.
• PDL supports the idea of iterative refinement.
• PDL makes changes easier.
• PDL is easier to maintain than other forms of design documentation since PDL remains along with the code and in sync with code-changes.

The author describes following steps in designing a routine:

• Prerequisites: Before doing any work on the routine, the job of the routine should be clearly defined and fits cleanly into the overall architecture.
• Problem definition: The problem the routine will solve should be stated in enough detail with regards to following:
  
  • Inputs to the routine
  • Outputs from the routine including the global variables affected
  • Information the routine will hide
  • How the routine will handle errors
• Name the routine: A routine should have a clear, unambiguous name. If there is problem in coming up with a good name, it usually indicates that the purpose of the routine is not clear.
• Decide on how to test the routine
• Think about efficiency: The author specifies two categories:
• If the system is not performance critical, the routine should be well modularized and is well readable. If it does not meet the performance criteria later, it can be replaced with a faster algorithm or more-efficient programming language. 
• If the system is performance critical, the architecture should clearly specify the space and time constraints and the routine should follow them.
• Research the algorithms and data structures:
• Write the PDL: This can be divided in several parts
• Write a concise statement of the purpose of the routine.
• Fill-in the high level PDL for the routine.
• Think about the data: If data manipulation is a prominent part of the routine, definitions of the key data structures are useful to have when you design the logic of the routine.
• Check the PDL: Review the PDL and think of how to explain it to someone else. Make sure it is easily understandable of what the routine does and how it does it.
• Iterate: Try different ideas in PDL before starting to code.
• Write the routine declaration:  Write the routine interface statement.
• Turn the PDL into high level comment and fill in the code below each comment: Each comment may translate into one or more lines of code.
• Check the code informally: Check each block of code and try to think of what it would take to break the block. 
• Clean up the leftovers:
• Check the routine interface and make sure that all input and output data is accounted for and all the parameters are used.
• Make sure routine does one thing and is loosely coupled with other routines.
• Check for unused data, undeclared variables and inaccurate variable names.
• Check for off-by one errors, improper nesting and infinite loops.
• Make sure proper indentation has been used to clarify the logical structure of the routine, the expressions and parameter lists.
• Make sure the PDL that was translated into comments is still accurate. Comments should provide algorithm descriptions, documentation on non-obvious dependencies and justification for unclear coding practices.
• Check the routine: Try to mentally execute the whole routine and see if there are any errors.
• Compile the routine: The author mentions about "Just One More Compile" syndrome where the programmer wants the routine to start working in just one more compilation effort. This leads to hasty, error-prone changes and takes more time in the long run.
• Debug the routine: Once the routine compiles, put it into a debugger and step through each line of code to make sure each line executes as you expect it to.
• Remove errors from the routine: If the routine is unusually buggy, don't patch it. Rewrite it. Creating an entirely new design for a buggy routine pays off.