千万要避免的五种程序注释方式-阿里云开发者社区

开发者社区> 开发与运维> 正文

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

简介:

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

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

1. 骄傲型程序员

01 public class Program
02 {
03     static void Main(string[] args)
04     {
05         string message = "Hello World!";  // 07/24/2010 Bob
06         Console.WriteLine(message); // 07/24/2010 Bob
07         message = "I am so proud of this code!"// 07/24/2010 Bob
08         Console.WriteLine(message); // 07/24/2010 Bob
09     }
10 }

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

2. 过时型程序员

01 public class Program
02 {
03     static void Main(string[] args)
04     {
05         /* This block of code is no longer needed
06          * because we found out that Y2K was a hoax
07          * and our systems did not roll over to 1/1/1900 */
08         //DateTime today = DateTime.Today;
09         //if (today == new DateTime(1900 1 1))
10         //{
11         //    today = today.AddYears(100);
12         //    string message = "The date has been fixed for Y2K.";
13         //    Console.WriteLine(message);
14         //}
15     }
16 }

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

3. 显然型程序员

01 public class Program
02 {
03     static void Main(string[] args)
04     {
05         /* This is a for loop that prints the
06          * words "I Rule!" to the console screen
07          * 1 million times each on its own line. It
08          * accomplishes this by starting at 0 and
09          * incrementing by 1. If the value of the
10          * counter equals 1 million the for loop
11          * stops executing.*/
12         for (int i = 0; i < 1000000; i++)
13         {
14             Console.WriteLine("I Rule!");
15         }
16     }
17 }

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

4. 传记型程序员

01 public class Program
02 {
03     static void Main(string[] args)
04     {
05        /* I discussed with Jim from Sales over coffee
06         * at the Starbucks on main street one day and he
07         * told me that Sales Reps receive commission
08         * based upon the following structure.
09         * Friday: 25%
10         * Wednesday: 15%
11         * All Other Days: 5%
12         * Did I mention that I ordered the Caramel Latte with
13         * a double shot of Espresso?
14        */
15         double price = 5.00;
16         double commissionRate;
17         double commission;
18         if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)
19         {
20             commissionRate = .25;
21         }
22         else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)
23         {
24             commissionRate = .15;
25         }
26         else
27         {
28             commissionRate = .05;
29         }
30         commission = price * commissionRate;
31     }
32 }

如果你非得在代码中提到某些必需的东西,也别提到人名。Jim from Sales(译注:销售人员Jim)也许离开这家公司了,那些阅读代码的程序员极可能根本就不知道他是谁,更甭提注释里那些毫无干系的事情。

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

01 public class Program
02 {
03     static void Main(string[] args)
04     {
05        //TODO: I need to fix this someday – 07/24/1995 Bob
06        /* I know this error message is hard coded and
07         * I am relying on a Contains function but
08         * someday I will make this code print a
09         * meaningful error message and exit gracefully.
10         * I just don’t have the time right now.
11        */
12        string message = "An error has occurred";
13        if(message.Contains("error"))
14        {
15            throw new Exception(message);
16        }
17     }
18 }

这类注释在某种程度上说是前面几种类型的大杂烩。TODO注释在项目初始开发阶段用处不小,但是如果几年后出现在产品代码中——那就会带来麻烦。如果有什么需要修补的,趁现在动手,而不要推迟到以后去做。

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

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

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

分享:
开发与运维
使用钉钉扫一扫加入圈子
+ 订阅

集结各类场景实战经验,助你开发运维畅行无忧

其他文章