Writing code using the Pseudocode Programming Process

Are you a planner, or a doer? Most programmers I have seen tend to lean toward the doer side of things. This is generally great but can lead to some design issues down the road. Without properly designing a class or routine, you can run into situations where you have to stop and rethink your approach, or in some instances have to scrap what you’ve written and start over!

A common and very simple process to help plan your class or routine is named the Pseudocode Programming Process. Steve McConnell, author of Code Complete, is a huge proponent of the this process:

The Pseudocode Programming Process defines a specific approach to using pseudocode to streamline the creation of code within the routines.

Once the pseudocode is written, you build the code around it and the pseudocode turns into programming-language comments. This eliminates most commenting effort. If the pseudocode follows the guidelines, the comments will be complete and meaningful.

The general idea is to iterate the pseudocode until the pseudocode statements become enough that you can fill in code below each statement and leave the original pseudocode as documentation.

Although I’m not a fan of commenting code, I think this process eases the pain of commenting and does result in a decent set of comments. McConnell also argues that this process increases the quality of your code and makes code reviews easier. I generally agree. I’ve found that thinking ahead, no matter how little, can result in code with less errors.

Let’s pretend we’re creating a method to weigh blog comments. Comments can get upvoted (not downvoted) which is only part of their weight. Their weight is also increased based on their age and text length. Let’s say they get a weight increase of 1 point per month, and an increase of 1 point per 200 characters. Anything under 20 characters gets a 1 point weight decrease. To get started with the Pseudocode Programming Process, write down, in a high level, what the method is supposed to do.

//Calculate a comment's weight

Great! First step down. Now, in a little deeper level:

//Increase weighting based on number of upvotes
//Increase weighting based on age
//Increase weighting based on text length

This gives us a general routine overview, but we can get better…

//Weighting starts at 0
//Add the number of upvotes
//Calculate age weighting of 1 point per month
//Add age weighting to overall weight
//Calculate text length weighting of 1 point per 200 characters
//   OR -1 point if under 20 characters
//Add text length weighting to overall weight

I think that’s a pretty good overview of the routine. It outlines each requirement in English in a high level. What you really want to avoid is using programming terms, like //Initialize an int for the weight.

The next step is the easiest – fill in the code!

public int CalculateCommentWeight(Comment comment)
{
    //Weighting starts at 0
    int weight = 0;

    //Add the number of upvotes
    weight += comment.UpVotes;

    //Calculate age weighting of 1 point per month
    int ageWeight = 0;
    DateTime today = DateTime.Now;
    int ageInMonths = GetMonthsBetweenDates(comment.PostDate, today);
    //Add age weighting to overall weight
    weight += ageInMonths;

    //Calculate text length weighting of 1 point per 200 characters
    //   OR -1 point if under 20 characters
    if(comment.Text.Length < 20)
    {
        weight -= 1;
    }
    else
    {
        int textWeight = CalculateTextWeight(comment.Text);

        //Add text length weighting to overall weight
        weight += textWeight;
    }

    return weight;
}

Now we have our routine with all requirements covered, and each requirement has it’s own comment. I would probably remove a few of those comments (especially those first two!), but overall I think we have a solid routine.

If you have a tendency to jump right in and code away, I advise, at least once, trying the Pseudocode Programming Process and see if it helps improve the quality of the code you write.