程序员应该避免的5种代码注释

开发 后端 开发工具
我特别讨厌这5种注释类型以及制造它们的程序员。希望你不是其中之一。

 

 

你有没有这样的经历:别人审查过你的代码之后给出的注释,你认为是没有必要的?注释代码是为了提高代码的可读性,目的是为了能让其他人更容易理解你的代码。

我特别讨厌这5种注释类型以及制造它们的程序员。希望你不是其中之一。

1.自以为很了不得的程序员

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

[[146030]]

这个程序员自认为写了一段很了不得的代码,所以觉得有必要用自己的名字对每行代码进行标记。实施版本控制系统(VCS)能实现对代码变更的问责,但是也不会这么明显知道谁应对此负责。

2.过时的程序员

  1. public class Program 
  2.     static void Main(string[] args) 
  3.     { 
  4.         /* This block of code is no longer needed 
  5.          * because we found out that Y2K was a hoax 
  6.          * and our systems did not roll over to 1/1/1900 */ 
  7.         //DateTime today = DateTime.Today; 
  8.         //if (today == new DateTime(1900, 1, 1)) 
  9.         //{ 
  10.         //    today = today.AddYears(100); 
  11.         //    string message = "The date has been fixed for Y2K."; 
  12.         //    Console.WriteLine(message); 
  13.         //} 
  14.     } 

[[146031]]

如果一段代码已不再使用(即过时),那就删除它——不要浪费时间给这些代码写注释。此外,如果你需要复制这段被删除的代码,别忘了还有版本控制系统,你完全可以从早期的版本中恢复代码。

3.多此一举的程序员

  1. public class Program 
  2.     static void Main(string[] args) 
  3.     { 
  4.         /* This is a for loop that prints the 
  5.          * words "I Rule!" to the console screen 
  6.          * 1 million times, each on its own line. It 
  7.          * accomplishes this by starting at 0 and 
  8.          * incrementing by 1. If the value of the 
  9.          * counter equals 1 million the for loop 
  10.          * stops executing.*/ 
  11.         for (int i = 0; i < 1000000; i++) 
  12.         { 
  13.             Console.WriteLine("I Rule!"); 
  14.         } 
  15.     } 

[[146032]]

我们都知道基础的编程逻辑是如何工作的——所以你不需要多此一举来解释这些显而易见的工作原理,虽然说你解释得很happy,但这只是在浪费时间和空间。

4.爱讲故事的程序员

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

[[146033]]

如果你一定要在注释里提及需求,那么不要涉及别人的名字。销售部门的Jim可能会离开公司,而且很有可能大多数程序员根本不知道这是何许人也。不要在注释里提及不相干的事实。

5.“以后再做”的程序员

  1. public class Program 
  2.     static void Main(string[] args) 
  3.     { 
  4.        //TODO: I need to fix this someday - 07/24/1995 Bob 
  5.        /* I know this error message is hard coded and 
  6.         * I am relying on a Contains function, but 
  7.         * someday I will make this code print a 
  8.         * meaningful error message and exit gracefully. 
  9.         * I just don't have the time right now. 
  10.        */ 
  11.        string message = "An error has occurred"
  12.        if(message.Contains("error")) 
  13.        { 
  14.            throw new Exception(message); 
  15.        } 
  16.     } 

[[146034]]

这种类型的注释包含了上面所有其他类型。如果是在项目的初始开发阶段,这种待做注释是非常有用的,但如果是在几年后的产品代码——那就会出问题了。如果有什么需要修复的,立马解决,不要把它搁置一边,“以后再做”。

如果你也常常犯这样的注释错误,如果你想了解注释的***做法,我建议你阅读类似于Steve McConnell写的《Code Complete》这样的好书。

责任编辑:王雪燕 来源: 码农网
相关推荐

2015-10-26 09:38:52

避免注释代码

2015-10-20 15:59:57

注释代码程序

2009-12-28 09:42:14

程序员

2017-11-20 22:28:43

程序员源代码编程

2012-01-10 14:43:48

程序员

2023-01-12 12:53:00

程序员离职违法

2012-11-20 10:20:03

程序员程序注释编程注释

2010-08-13 10:00:19

程序员注释

2011-12-19 09:40:21

程序员

2015-07-02 11:20:17

程序员代码

2016-06-03 15:18:45

程序员

2014-11-10 09:46:57

程序员

2009-03-13 15:18:45

程序员饮食杂谈

2013-04-01 15:51:09

程序员管理

2011-04-15 14:10:21

代码程序员

2017-12-19 20:35:22

程序员中兴事件自杀

2016-04-11 17:49:33

程序员外包

2020-12-07 10:19:01

程序员技术IT

2017-11-09 12:33:02

程序员代码技巧

2010-12-13 14:37:36

.NET开发
点赞
收藏

51CTO技术栈公众号