5 Types of Comments to Avoid Making in Your Code

Have you ever been reviewing code and come across a comment that you deemed was unnecessary? Commenting your code is meant to improve the readability of your code and make it more understandable to someone other than the original developer.

I have identified 5 types of comments that really annoy me and the types of programmers who make them. I hope after reading this you won’t be one who falls into one of these categories. As a challenge, you can try to match up these comment programmers with the 5 types of programmers.

1. The Proud Programmer

public class Program
{
    static void Main(string[] args)
    {
        string message = "Hello World!";  // 07/24/2010 Bob
        Console.WriteLine(message); // 07/24/2010 Bob
        message = "I am so proud of this code!"; // 07/24/2010 Bob
        Console.WriteLine(message); // 07/24/2010 Bob
    }
}

This programmer is so proud of his code that he feels the need to tag every line of code with his initials. Implementing a version control system (VCS) allows for accountability in code changes, but at first glance it won’t be so obvious who is responsible.

2. The Obsolete Programmer

public class Program
{
    static void Main(string[] args)
    {
        /* This block of code is no longer needed
         * because we found out that Y2K was a hoax
         * and our systems did not roll over to 1/1/1900 */

        //DateTime today = DateTime.Today;
        //if (today == new DateTime(1900, 1, 1))
        //{
        //    today = today.AddYears(100);
        //    string message = "The date has been fixed for Y2K.";
        //    Console.WriteLine(message);
        //}
    }
}

If a piece of code is no longer used (i.e. Obsolete), delete it – don’t clutter your working code with several lines of unnecessary comments. Besides if you ever need to replicate this deleted code you have a version control system, so you can recover the code from an earlier revision.

3. The Obvious Programmer

public class Program
{
    static void Main(string[] args)
    {
        /* This is a for loop that prints the
         * words "I Rule!" to the console screen
         * 1 million times, each on its own line. It
         * accomplishes this by starting at 0 and
         * incrementing by 1. If the value of the
         * counter equals 1 million the for loop
         * stops executing.*/

        for (int i = 0; i < 1000000; i++)
        {
            Console.WriteLine("I Rule!");
        }
    }
}

We all know how basic programming logic works – this is not “Introduction to Programming.” You don’t need to waste time explaining how the obvious works, and we’re glad you can explain how your code functions – but it’s a waste of space.

4. The Life Story Programmer

public class Program
{
    static void Main(string[] args)
    {
       /* I discussed with Jim from Sales over coffee
        * at the Starbucks on main street one day and he
        * told me that Sales Reps receive commission
        * based upon the following structure.
        * Friday: 25%
        * Wednesday: 15%
        * All Other Days: 5%
        * Did I mention that I ordered the Caramel Latte with
        * a double shot of Espresso?
       */

        double price = 5.00;
        double commissionRate;
        double commission;
        if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)
        {
            commissionRate = .25;
        }
        else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)
        {
            commissionRate = .15;
        }
        else
        {
            commissionRate = .05;
        }
        commission = price * commissionRate;
    }
}

If you have to mention requirements in your comments, don’t mention people’s names. Jim from sales probably moved on from the company and most likely the programmers reading this won’t know who he is. Not to mention the fact that it everything else in the comment is irrelevant.

5. The Someday Programmer

public class Program
{
    static void Main(string[] args)
    {
       //TODO: I need to fix this someday – 07/24/1995 Bob
       /* I know this error message is hard coded and
        * I am relying on a Contains function, but
        * someday I will make this code print a
        * meaningful error message and exit gracefully.
        * I just don’t have the time right now.
       */

       string message = "An error has occurred";
       if(message.Contains("error"))
       {
           throw new Exception(message);
       }
    }
}

This type of comment is sort of a catch-all it combines all the other types. The TODO comment can be very useful when you are in the initial development stages of your project, but if this appears several years later in your production code – it can spell problems. If something needs to be fixed, fix it now and do not put it off until later.

If you are one who makes these types of comments or would like to learn best practices in comment usage, I recommend reading a book like Code Complete by Steve McConnell. This is one of the books that I recommend all programmers should own.

Or Perhaps you can learn how to stop commenting your code altogether.

Do you see any other unnecessary or annoying comments in your code? Please feel free to share.

Update (11/11/11): I found some additional funny code comments: 10 “Best” Code Comments

Tagged with: , , , , , , , , , , , ,
Posted in Career
55 comments on “5 Types of Comments to Avoid Making in Your Code
  1. Adel says:

    I don’t agree with point 5. Most developers dont have the luxury of “fix it now and do not put it off until later”. So long as their is a task management system that mentions that so it does not fall out of scope and is visible to project managers then it should be fine.

    These are mainly used not for bug fixes (as they should obviously be fixed) but if a developer notices something quirky happening with their code and they “kind-of” know how to reproduce it, even though they havent desided on the best approach for it.

  2. Mams says:

    You forget the “bitchin’ type” who let comment like “This patch is to fix the piece of crap below”

    and the “ascii type” who comment in a form of ascii art.

    I would considerer my-self part ascii part bitchin part innapropriate jokes

  3. You also need to include the “invisible programmer” commenter, who doesn’t leave a single comment clarifying why they did some wacky implementation of something that may or may not be important to keep.

    “Oh,” you might say, “it’s in the specs”. WHAT specs??

  4. candra says:

    now i know, I am absolete programer :D

  5. ooter says:

    I think the appropriate comment should be in form of algorithm instruction which is (usually) concise, non-ambiguous and expressive. Also this helps to understand the whole code by skimming the comments and comprehend it without digging into the “nitty-gritty” details. Also the comment helps (you) to understand what you are really doing. If you can’t describe in short sentence “what’s goin’ on here” – sign for a bad programming practice.

5 Pings/Trackbacks for "5 Types of Comments to Avoid Making in Your Code"
  1. === popurls.com === popular today…

    yeah! this story has entered the popular today section on popurls.com…

  2. [...] morning's short read is "5 Types of Comments to Avoid Making in Your Code".  No developer doubts the benefit of good comments, but when the signal-to-noise ratio tips in [...]

  3. [...] post over on Repeat Geek about 5 Types of Comments to Avoid Making in Your Code is good advice, and it rings true for anybody who slings variables – we’re all seen [...]

  4. [...] 5 Types of Comments to Avoid Making in Your Code Categories: Article, Coding Tip, Random Tags: article, Code, codebases, Comments, Funny Comments (0) Trackbacks (0) Leave a comment Trackback [...]

Leave a Reply