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

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

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

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

1. 骄傲型程序员

  1. public class Program  
  2. {  
  3.     static void Main(string[] args)  
  4.     {  
  5.         string message = "Hello World!";  // 07/24/2010 Bob  
  6.         Console.WriteLine(message); // 07/24/2010 Bob  
  7.         message = "I am so proud of this code!"// 07/24/2010 Bob  
  8.         Console.WriteLine(message); // 07/24/2010 Bob  
  9.     }  

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

2. 过时型程序员

  1. public class Program  
  2. {  
  3.     static void Main(string[] args)  
  4.     {  
  5.         /* This block of code is no longer needed  
  6.          * because we found out that Y2K was a hoax  
  7.          * and our systems did not roll over to 1/1/1900 */ 
  8.         //DateTime today = DateTime.Today;  
  9.         //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.     }  

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

3. 显然型程序员

  1. public class Program  
  2. {  
  3.     static void Main(string[] args)  
  4.     {  
  5.         /* This is a for loop that prints the   
  6.          * words "I Rule!" to the console screen   
  7.          * 1 million times each on its own line. It  
  8.          * accomplishes this by starting at 0 and   
  9.          * 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.     }  

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

4. 传记型程序员

  1. public class Program  
  2. {  
  3.     static void Main(string[] args)  
  4.     {  
  5.        /* I discussed with Jim from Sales over coffee   
  6.         * at the Starbucks on main street one day and he  
  7.         * told me that Sales Reps receive commission   
  8.         * based upon the following structure.   
  9.         * 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.     }  

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

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

  1. public class Program  
  2. {  
  3.     static void Main(string[] args)  
  4.     {  
  5.        //TODO: I need to fix this someday – 07/24/1995 Bob  
  6.        /* I know this error message is hard coded and  
  7.         * I am relying on a Contains function but   
  8.         * someday I will make this code print a   
  9.         * 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.     }  

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

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

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

原文链接:http://www.oschina.net/question/253614_79956

责任编辑:林师授 来源: OSCHINA
相关推荐

2015-08-20 09:06:48

程序员

2013-07-17 17:21:49

避免代码注释移动开发移动互联网

2013-07-16 10:49:11

代码注释

2021-12-02 18:07:53

云网络部署云端云计算

2019-03-27 08:27:32

物联网IOT技术

2022-12-29 08:46:15

IT采购投资

2022-12-07 11:24:51

首席信息官IT

2022-01-10 06:52:59

查询MySQL字段

2011-11-25 10:25:27

SpringJava

2011-02-28 13:51:30

Spring事物配置

2010-08-27 09:10:15

网络隐私

2009-06-19 18:26:38

Spring事务配置

2021-06-28 10:12:34

云计算云平台云计算架构

2016-05-25 10:03:51

JavaScript内存泄露

2014-02-19 11:12:04

WAN优化WAN

2023-01-06 09:02:55

CIOCEO运营

2017-07-04 16:34:33

边缘计算方式

2010-08-13 13:25:53

Flex页面跳转

2018-09-10 15:58:49

2022-01-13 19:25:28

服务方式TCP
点赞
收藏

51CTO技术栈公众号