#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;