千万要避免的五种程序注释方式
2012-11-20 23:17
330 查看
你是否曾在检查代码时碰到一条在你看来多余的注释？在代码中使用注释的目的是提升代码的可读性，以让那些非原始代码开发者能更好地理解它们。
我甄别出5类让我不胜其扰的注释及5类生成它们的程序员。我希望读过本篇之后，你不会与他们一样坠入同一条河流。作为一项挑战，你不妨把写这5类注释的程序员与5类程序员[英文]作一下匹配。
这类程序员对其代码自视甚高，以至于他觉得有必要在每行代码后都要签上自己的大名。应用版本控制系统（VCS）是能知道谁修改了代码，但是乍看之下责任人也不会如此打眼。
如果一段代码不再使用了（也就是过时了），请删除它——勿要让你的工作代码被数行冗余的注释弄得七零八乱。而且，你任何时候需要复制这段删除的代码，都可以使用版本控制系统，这样你便能从以前版本中恢复出它来。
我们都知道编程的基本工作逻辑——这可不是什么“编程入门”！你无需浪费时间解释显而易见的程序工作原理，虽然我们很高兴看到你愿意解释代码的功能——但这不过是画蛇添足。
如果你非得在代码中提到某些必需的东西，也别提到人名。Jim from Sales（译注：销售人员Jim）也许离开这家公司了，那些阅读代码的程序员极可能根本就不知道他是谁，更甭提注释里那些毫无干系的事情。
这类注释在某种程度上说是前面几种类型的大杂烩。TODO注释在项目初始开发阶段用处不小，但是如果几年后出现在产品代码中——那就会带来麻烦。如果有什么需要修补的，趁现在动手，而不要推迟到以后去做。
如果你不幸是生成这些类型注释的人，或者你想学习注释用法的最佳实践，我推荐你阅读Steve McConnell写的Code Complete（《代码大全》）。这是一本我建议程序员必读的书籍，OSC地址 http://my.oschina.net/justjavac/blog/66624。
你是否在自己的代码中看到了其它类型多余或扰人的注释？请不吝分享。
我甄别出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 | } |
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 ; 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 | } |
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 | } |
如果你不幸是生成这些类型注释的人，或者你想学习注释用法的最佳实践，我推荐你阅读Steve McConnell写的Code Complete（《代码大全》）。这是一本我建议程序员必读的书籍，OSC地址 http://my.oschina.net/justjavac/blog/66624。
你是否在自己的代码中看到了其它类型多余或扰人的注释？请不吝分享。
内容来自用户分享和网络整理，不保证内容的准确性，如有侵权内容，可联系管理员处理 
相关文章推荐