#975 – Guidelines for Commenting Your Code

The primary goal of including comments in your code is to make the code + comments self-documenting enough that a developer other than the original author can understand what the code does and how it does it.

Guidelines for well commented code include:

• Wherever possible, the code should “self document”:
  • Meaningful names for variables and methods
  • Consistent layout
  • Modularized code — each method performs a single task
  • Minimize nesting, where possible
• Write effective comments:
  • Don’t just repeat what the code does
  • Use a comment to summarize a block of code that follows the comment, providing a high-level description of what the code does
  • Describe what and why, rather than how.  The code describes how and sometimes what.  Comments add to the what and also talk about why.
  • Modify comments when you modify code, if appropriate (i.e. keep the comments current)
  • Don’t comment tricky code–rewrite the code
  • Write for humans

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

#475 – Comments Occuring within String Literals Are Treated as Part of the String

Recall that comments in C# can be of two forms–either single line or delimited comments.

            // This is a single line comment
            int x = 12;  // So is this

            /* Delimited comment here */

            /* This is
             * a multiline delimited comment
             * comment */

If something that looks like a comment appears within a string, it isn’t treated by the compiler as a comment, but just as part of the string.

            Console.WriteLine("A C# comment looks like this:  // This is a comment");
            Console.WriteLine("It might also look like this:  /* Good morning Pompeii */");