千万要避免的五种程序注释方式

justjavac 发布于 2012/11/20 09:13
阅读 13K+
收藏 83

你是否曾在检查代码时碰到一条在你看来多余的注释?在代码中使用注释的目的是提升代码的可读性,以让那些非原始代码开发者能更好地理解它们。

我甄别出5类让我不胜其扰的注释及5类生成它们的程序员。我希望读过本篇之后,你不会与他们一样坠入同一条河流。作为一项挑战,你不妨把写这5类注释的程序员与5类程序员[英文]作一下匹配。

1. 骄傲型程序员

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

这类程序员对其代码自视甚高,以至于他觉得有必要在每行代码后都要签上自己的大名。应用版本控制系统(VCS)是能知道谁修改了代码,但是乍看之下责任人也不会如此打眼。

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

如果一段代码不再使用了(也就是过时了),请删除它——勿要让你的工作代码被数行冗余的注释弄得七零八乱。而且,你任何时候需要复制这段删除的代码,都可以使用版本控制系统,这样你便能从以前版本中恢复出它来。

3. 显然型程序员

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

我们都知道编程的基本工作逻辑——这可不是什么“编程入门”!你无需浪费时间解释显而易见的程序工作原理,虽然我们很高兴看到你愿意解释代码的功能——但这不过是画蛇添足。

4. 传记型程序员

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 from Sales(译注:销售人员Jim)也许离开这家公司了,那些阅读代码的程序员极可能根本就不知道他是谁,更甭提注释里那些毫无干系的事情。

5. “总有一天”型程序员

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注释在项目初始开发阶段用处不小,但是如果几年后出现在产品代码中——那就会带来麻烦。如果有什么需要修补的,趁现在动手,而不要推迟到以后去做。

如果你不幸是生成这些类型注释的人,或者你想学习注释用法的最佳实践,我推荐你阅读Steve McConnell写的Code Complete(《代码大全》)。这是一本我建议程序员必读的书籍,OSC地址 http://my.oschina.net/justjavac/blog/66624

你是否在自己的代码中看到了其它类型多余或扰人的注释?请不吝分享。

扩展阅读:十大注释技巧教你如何书写容易阅读的代码

加载中
1
拉菲一箱
拉菲一箱

注释有2种含义:

1、表示该代码是啥含义

2、这部分修改是由谁,因为什么原因而修改的

需要表述上述2种含义时才加注释,其他都是废话

异常爱
异常爱
说的太对了,总结的真好
0
十一文
十一文
代码大全> 的确必读!
0
回去干活
回去干活

还好哥写代码从来不写注释。

因为哥的代码直接就能读懂,找不到复杂的地方

justjavac
justjavac
回复 @fhp0917 : http://www.zhihu.com/question/20594192
justjavac
justjavac
回复 @fhp0917 : +1
fhp0917
fhp0917
好的代码不需要注释,代码本身就是注释
0
lyle_5
lyle_5
最后一个中。。。可是我还在初期,应该不会遗留。
lyle_5
lyle_5
@Nemesis_E 嗯,今天就不写新的了,把所有的遗留都弄完,不过估计以后还会这样,记不住教训。。。
Nemesis_E
Nemesis_E
反正 我是遗留了不少 未来实现的 通常都没有未来了
0
swekaFruX8
swekaFruX8
好搞笑,完全是看笑话啊。。。
0
黑薯
黑薯

我代码某行注释:

JXU4RkQ5JXU5NzAwJXU2QzQyJXU1QzMxJXU2NjJGJXU1Rjg4JXU1NzUxJXU3MjM5JTJDJXU2MjExJXU0RTVGJXU2NzI4JXU1MjlFJXU2Q0Q1


0
抢小孩糖吃
抢小孩糖吃
不过我最近在写一个C51的编程框架 注释部分特别想写成 编程入门的类型来帮助使用这套框架的人 看来我还是需要在考虑考虑
0
崔钢
崔钢
注释仅需要说明做了什么,就可以了。当然,做到这点其实也并不容易。
0
Ryan-瑞恩
Ryan-瑞恩
我么看出来我属于那种,,,,,,我的注释就只说明函数是干什么的。
返回顶部
顶部