软件下载 | 资讯教程 | 最近更新 | 下载排行 | 一键转帖 | 发布投稿
您的位置:最火下载站 > 网络编程 > 编程综合 > 五种应该避免的代码注释

五种应该避免的代码注释

在酷壳,有很多文章都提到了代码注释,如:《十条不错的编程观点》、《优质代码的十诫》、《整洁代码的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!");
        }
    }
}

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

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

相关阅读
网友评论
栏目导航
推荐软件