注释的有趣写法

顺着极客头条的链接，看到几个关于注释的几篇文章，汇在一起共享。

1. 我承认，这样的注释，我写过

来源：

（英）5 comment styles should be avoided http://www.pixelstech.net/article/1353517032-5-comment-styles-should-be-avoided

（中）千万要避免的五种程序注释方式   http://www.oschina.net/question/253614_79956

正文：

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


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.

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

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.

2. 这样的注释在各种段子中也见过

来源：

Do you have this kind of comments in your source code? http://www.pixelstech.net/article/1378271050-Do-you-have-this-kind-of-comments-in-your-source-code-

正文：

Writing runnable codes is the necessary capability of a programmer, writing understandable comments is also a skill a programmer should acquire. There is some famous saying that bad comment is worth than no comment. Usually your code will be maintained by other people, if you provide them some difficult to understand or misguided comments, this will be nightmare to them. While in some other time, programmers may put some funny comments in their codes which may make others laugh. Today we share some comments which are full of humor.

// 
 
// Dear maintainer:
 
// 
 
// Once you are done trying to 'optimize' this routine,
 
// and have realized what a terrible mistake that was,
 
// please increment the following counter as a warning
 
// to the next guy:
 
// 
 
// total_hours_wasted_here = 42
 
//

// When I wrote this, only God and I understood what I was doing
 
// Now, God only knows

// sometimes I believe compiler ignores all my comments

// I dedicate all this code, all my work, to my wife, Darlene, who will 
 
// have to support me and our three children and the dog once it gets 
 
// released into the public.

// drunk, fix later

// Magic. Do not touch.

#define TRUE FALSE
 
// Happy debugging suckers

long long ago; /* in a galaxy far far away */

/**
 
 * Always returns true.
 
 */
 
public boolean isAvailable() {
 
    return false;
 
}

Did you write this kind of comments in your source code before?  

3. 艺术，还是绝学？实际工作中还是少这样玩花的

来源：

（英）Art of code comment   http://www.pixelstech.net/article/1376903956-Art-of-code-comment

（中）失传的绝学：代码注释的艺术 http://segmentfault.com/a/1190000000265197

正文：

Note : This post is just for fun. Please be careful about these tricks.

Code comment is to provide complementary comment to abstract codes. We will introduce two comment styles while we are debugging our codes. we should avoid these styles in production codes.


1. if else style
Only execute eatKfc()

//*                     
eatKfc();
/*/                     
eatMcdonalds();        
//*/

Only execute eatMcdonalds()

/*
eatKfc();
/*/
eatMcdonalds();
//*/

Execute both

//*
eatKfc();
//*/
eatMcdonalds();
//*/

2. Block comment

Don't comment

/**/
var foo = function() {
    ...
};
/**/

Block comment 1

/** /
var foo = function() {
    ...
};
/**/

Block comment 2

/**
var foo = function() {
    ...
};
/**/

These are old age comment styles. Now the advanced IDEs support shortcut keys for commenting some codes.