Programming

Code Complete 2 – Steve McConnell – Pseudocode Programming Process

I just love Steve McConnell’s classic book Code Complete 2, and I recommend it to everyone in the Software ‘world’ who’s willing to progress and sharpen his skills.

Other blog posts in this series:

The benefits you can expect from using the pseudocode:

  • makes reviews easier – you can review detailed designs without examining the source code
  • supports the idea of iterative refinement
  • makes changes easier – a few lines of pseudocode are easier to change than a page of code
  • it’s easier to maintain than other forms of design documentation

Steps in building a routine

  1. Design the routine
  2. Code the routine
  3. Check the code
  4. Clean up loose ends
  5. Repeat as needed

1. Design the routine

  • Check the prerequisites to see that the job of the routine is well defined and fits cleanly into the overall design
  • Define the problem the routine will solve
  • Name the routine – good routine names are one sign of a superior program and they’re not easy to come up with
  • Decide how to test the routine
  • Research functionality available in the standard libraries – the single biggest way to improve both the quality of your code and your productivity is to reuse good code
  • Think about error handling – think about all the things that could possibly go wrong in the routine
  • Think about efficiency – in a vast majority of systems, efficiency isn’t critical. Design your routine so that it will meet its resource and speed goals
  • Research the algorithms and data types – if functionality isn’t available in the available libraries, it might still be described in an algorithms book
  • Write the pseudocode – you might not have much in writing after you finish the preceding steps. The main purpose of the steps is to establish a mental orientation that’s useful when you actually write the routine
  • Think about the data
  • Check the pseudocode – once you’ve written the pseudocode and designed the data, take a minute to review the pseudocode you’ve written. Back away from it, and think about how you would explain it to someone else
  • Try a few ideas in pseudocode, and keep the best (iterate)

2. Code the routine

  • Start with pseudocode
  • Write the routine declaration
    • Turn the original header comment into a programming-language code comment above declaration
  • Write the first and last statements, and turn the pseudocode into high-level comments
    /* Header comment about what routine does */
    Status ReportErrorMessage(
        ErrorCode errorToReport
    ) {
        //set the default status to "fail"

        //if the error code is valid, display the error message 
        //and declare success

        //if the error code isn't valid, notify the user that an internal 
        //error has been detected

        //return status information
    }
  • Fill in the code below each comment 
/* Header comment about what routine does */
Status ReportErrorMessage(
    ErrorCode errorToReport
) {
    //set the default status to "fail"
    Status errorMessageStatus = Status_Failure;

    //if the error code is valid, display the error message 
    //and declare success
    if ( errorMessage.ValidCode() ) {
        DisplayMessage( errorMessage.Text() );
        errorMessageStatus = Status_Success;
    }

    //if the error code isn't valid, notify the user that an internal 
    //error has been detected
    else {
        DisplayMessage( "Internal Error: Invalid error code in ReportErrorMessage()" );
    }

    //return status information
    return errorMessageStatus;
}

Each comment should normally expand to about 2 to 10 lines of code.

3. Check the code

  • Mentally check the routine for errors

A working routine isn’t enough. If you don’t know why it works, study it, discuss it, and experiment with alternative designs until you do.

Compile the routine after reviewing it. It might seem inefficient to wait this long to compile. You’ll benefit in several ways, however, by not compiling until late in the process. After the first compile, you step up the pressure: “I’ll get it right with just one more compile.” The “Just One More Compile” syndrome leads to hasty, error-prone changes that take more time in the long run.

  • Step through the code in the debugger
  • Test the code

4. Clean up leftovers

  • Check the routine’s interface. Make sure that all input and output data is accounted for and that all parameters are used
  • Check for general design quality. Make sure the routine does one thing and does it well, that it’s loosely coupled to other routines, and that it’s designed defensively
  • Check the routine’s variables (inaccurate variable names, unused objects, undeclared variables, and so on)
  • Check routine’s statements and logic
  • Remove redundant comments

Alternatives to the PPP

  • Test-first development – popular development style in which test cases are written before writing any code
  • Refactoring – development approach in which you improve code through a series of semantic preserving transformation
  • Design by contract – development approach in which each routine is considered to have preconditions and postconditions
  • Hacking? – some programmers try to hack their way toward working code rather than using a systematic approach like the PPP. If you’ve ever found that you’ve coded yourself into a corner in a routine and have to start over, that’s an indication that the PPP might work better
Written by Nikola Brežnjak