现在的位置: 首页 > 综合 > 正文

五种应该避免的代码注释

2014年02月15日 ⁄ 综合 ⁄ 共 2471字 ⁄ 字号 评论关闭

一、自恋型注释

(注:原文为Proud,我觉得“自恋”更好一点)

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

原文:这样的程序员对于自己的代码改动非常骄傲和自恋,所以,他觉得需在在这些自己的代码上标上自己的名字。其实,一个版本控制工具(如:CVS或Subversion)可以完整地记录下所有的关于代码的改动的和作者相关的一切信息,只不过不是那么明显罢了。

二、废弃代码的注释

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

原文:如果某段代码不再使用了,那就应该直接删除。我们不应该使用注释来标准废弃的代码。同样,我们有版本控制工具来管理我们的源代码,在版本控制工具里,是不可能有代码能被真正的物理删除的。所以,你总是可以从以前的版本上找回你的代码的。

三、明显的注释

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

原文:看看上面的例子,代码比注释还容易读。是的,大家都是程序员,对于一些简单的,显而易见的程序逻辑,不需要注释的。而且,你不需要在你的注释中教别人怎么编程,你这是在浪费时间去解释那些显而易见的东西。你应该用注释去解释你的代码功能,原因,想法,而不是代码本身。

四、故事型注释

  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,如果有不懂的,你可以去问他。其实,这根本没有必要在注释中提到一些和代码不相干的事。

五、“TODO”注释

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

原文:当你在初始化一个项目的时候,TODO注释是非常有用的。但是,如果这样的注释在你的产品源码中出现了N多年,那就有问题了。如果有BUG要被fix,那就Fix吧,没有必要整一个TODO。

原文地址http://www.csdn.net/article/2010-07-28/277372

抱歉!评论已关闭.