5 comment styles should be avoided

Have you ever found some superfluous comments while checking others codes? The purpose of using comments in the code is to enhance the readability of the code, so that non-original code developers can understand them better and easier.

I summarized 5 kinds of comment styles and the developers who write them. Hope you don't do the same thing as below in your application development process.

1. Arrogant comments

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 kind of programmers are very proud of their codes so that they put their names on each line of the comment. Actually we can use VCS(Version Control System) to find who modified the codes.

2. Out-dated comments

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 not needed anymore, please delete them-- Avoid messing up your working codes with the out-dated codes.

3. Redundant comments

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 basic logic of programming-- It is not a kind of entry level program. You no need to waste your time putting comments to some codes which everyone knows what they do. Although we are glad that you are willing to explain the use of the codes, sometimes they are just redundant.

4. Story comments

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

Even if you need to mention some necessary stuff in your codes, please don't mention people's name. Jim may have left the company. Don't mention some unrelated information in your comments.

5. TODO comments

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 kind of comments is a mix of above four kinds of comments. TODO is very useful at the beginning of a project, but it's troublesome if it's still in the codes after a few years.

If you like writing one type of above comments, or if you want to learn some best practices of writing comments, we recommend you to read Code Complete written by Steve McConnel.

Source : http://www.oschina.net/question/253614_79956