#974 – Well Written Code Includes Well Written Comments

Well written code includes well written comments.  Including comments that help explain what the code is doing is part of the process of writing high quality source code.

The main goal of well commented code is to make the code easier to maintain.  Software that goes into production often ends up being used for many years.  This means that the amount of money spent maintaining the software can be far greater than the amount spent to develop the software.  During development, anything that you can do to make maintaining the software easier is a good investment.

Comments should not merely parrot back what the code is doing.

            // Add two to the age
            age += 2;

Instead, good comments provide more information than is possible by reading the code.

            // As part of calculating longevity, adjust for being a smoker.
            // See http://somepeerreviewestudyonsmoking.com
            if (theCustomer.IsSmoker())
                predictedMaxAge += 2;

About Sean
Software developer in the Twin Cities area, passionate about software development and sailing.

4 Responses to #974 – Well Written Code Includes Well Written Comments

  1. Pingback: Dew Drop – November 14, 2013 (#1667) | Morning Dew

  2. Ilkin says:

    Thanks for good articles.
    Please give article on pseudocode.

  3. Tim says:

    I would have though predictedMaxAge would have been reduced for a smoker 🙂

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: