五种应该避免的代码注释

酷壳： http://CoolShell.cn/ 

原文： http://coolshell.cn/?p=2746

 

在酷壳，有很多文章都提到了代码注释，如：《十条不错的编程观点》、《优质代码的十诫》、《整洁代码的4个提示》、《惹恼程序员的十件事》等等。今天，某国外的程序员在这里列举五种应该避免的程序注释，我觉得比较有道理，但我觉得有少数几个观点也并不绝对。所以，我把原文的这五种应该避免的程序注释罗列在下面，并放上原作者和我的个人观点作为比较。希望对大家有用。

一、自恋型注释

（注：原文为Proud，我觉得“自恋”更好一点）

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

原文：这样的程序员对于自己的代码改动非常骄傲和自恋，所以，他觉得需在在这些自己的代码上标上自己的名字。其实，一个版本控制工具（如：CVS或Subversion）可以完整地记录下所有的关于代码的改动的和作者相关的一切信息，只不过不是那么明显罢了。

陈皓：我同意原文的观点。在我的团队里也有这样的事情发生。有段时间我认真思考过这样的事情，是否应该把这样的事情在代码中铲除出去。后来，我觉得，允许这样的行为并不一定是坏事，因为两点：

 

1. 调动程序员下属的积极性可能更为重要。即然，这种方式可以让程序员有骄傲的感觉，能在写代码中找到成就感，为什么要阻止呢？又不是什么大问题。
2. 调动程序员的负责任的态度。程序员敢把自己的名字放在代码里，说明他对这些代码的信心，是想向大家展示其才能。所以，他当然知道，如果这段他加入的代码有问题的话，他的声誉必然受到损失，所以，他敢这么干，也就表明他敢于对自己的代码全面的负责。这不正是我们所需要的？！

所以，基于上述考虑，我个人认为，从代码的技术角度上来说，这样的注释很不好。但从团队的激励和管理上来说，这样的方式可能也挺好的。所以，我并不阻止也不鼓励这样的注释。关键在于其是否能有更好的结果。

二、废弃代码的注释

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

原文：如果某段代码不再使用了，那就应该直接删除。我们不应该使用注释来标准废弃的代码。同样，我们有版本控制工具来管理我们的源代码，在版本控制工具里，是不可能有代码能被真正的物理删除的。所以，你总是可以从以前的版本上找回你的代码的。

陈皓：我非常同意这样的观点。只要你是废弃的，就应该是删除，而不是注释掉。注释并不是用来删除代码的。也许你会争论到，在迭代开发中，你觉得被注释的代码很有可能在未来会被使用，但现在因为种种问题暂时用不到，所以，你先注释着，然后等到某一天再enable它。所以你注释掉一些未来会有的程序。在这样的情况，你可以注释掉这段代码，但你要明白，这段代码不是“废弃”的，而是“临时”不用的。所以，我在这里提醒你，请不要教条式地在你的程序源码中杜绝这样的注释形式，是否“废弃”是其关键。

三、明显的注释

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!");
        }
    }
}

原文：看看上面的例子，代码比注释还容易读。是的，大家都是程序员，对于一些简单的，显而易见的程序逻辑，不需要注释的。而且，你不需要在你的注释中教别人怎么编程，你这是在浪费时间去解释那些显而易见的东西。你应该用注释去解释你的代码功能，原因，想法，而不是代码本身。

陈皓：非常同意。最理解的情况是你的代码写得直接易读，代码本身就是自解释的，根本不需要注释。这是最高境界。注释应该说明下面的代码主要完成什么样的功能，为什么需要他，其主要算法怎么设计的，等等。而不是解释代码是怎么工作的。这点很多新手程序员都做得不够好。别外，我需要指出的是，代码注释不宜过多，如果太多的话，你应该去写文档，而不是写注释了。

四、故事型注释

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

原文：如果你不得不在你的代码注释中提及需求，那也不应该提及人名。在上面的示例中，好像程序想要告诉其它程序员，下面那些代码的典故来自销售部的Jim，如果有不懂的，你可以去问他。其实，这根本没有必要在注释中提到一些和代码不相干的事。

陈皓：太同意了。这里仅仅是代码，不要在代码中掺入别的和代码不相干的事。这里你也许会有以下的争辩：

1. 有时候，那些所谓的“高手”逼着我这么干，所以，我要把他的名字放在这里让所有人看看他有多SB。
2. 有时候，我对需求并不了解，我们应该放一个联系人在在这里，以便你可以去询问之。

对于第一点，我觉得这是一种情绪化。如果你的上级提出一些很SB的想法，我觉得你应该做的是努力去和他沟通，说明你的想法。如果这样都不行的话，你应该让你的经理或是那个高手很正式地把他的想法和方案写在文档里或是电子邮件里，然后，你去执行。这样，当出现问题的时候，你可以用他的文档和邮件作为你的免责证据，而不是在代码里干这些事。

对于第二点，这些需求的联系人应该是在需求文档中，如果有人有一天给你提了一个需求，你应该把其写在你的需求文档中，而不是你的代码里。要学会使用流程来管理你的工作，而不是用注释。

最后，关于故事型的注释，我需要指出也有例外的情况，我们团队中有人写注释喜欢在注释或文档里写一些名人名言（如 22条经典的编程引言，编程引言补充，Linus Torvalds 语录 Top 10 ），甚至写一些小笑话，幽默的短句。我并不鼓励这么做，但如果这样有利于培养团队文化，有利于让大家对工作更感兴趣，有利于大家在一种轻松愉快的环境下读/写代码，那不也是挺好的事吗？

另外，做为一个管理者，有时候我们应该去看看程序员的注释，因为那里面可能会有程序员最直实的想法和情绪（程序员嘴最脏??）。了解了他们的想法有利于你的管理。

五、“TODO”注释

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

原文：当你在初始化一个项目的时候，TODO注释是非常有用的。但是，如果这样的注释在你的产品源码中出现了N多年，那就有问题了。如果有BUG要被fix，那就Fix吧，没有必要整一个TODO。

陈皓：是的，TODO是一个好的标志仅当存在于还未release的项目中，如果你的软件产品都release了，你的代码里还有TODO，这个就不对了。也许你会争辩说，那是你下一个版本要干的事。OK，那你应该使用项目管理，或是需求管理来管理你下一个版本要干的事，而不是使用代码注释。通常，在项目release的前夕，你应该走查一下你代码中的TODO标志，并且做出决定，是马上做，还是以后做。如果是以后做，那么，你应该使用项目管理或需求管理的流程。

上述是你应该避免使用的注释，以及我个人的一些观点，也欢迎你留下你的观点！