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

Share To Facebook Twitter

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

我特别讨厌这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. }
  10. }

这个程序员自认为写了一段很了不得的代码,所以觉得有必要用自己的名字对每行代码进行标记。实施版本控制系统(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. }
  16. }

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

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

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

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

如果你一定要在注释里提及需求,那么不要涉及别人的名字。销售部门的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. }
  18. }

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

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

(责任编辑:IT)

发表评论