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

朱雀 2022-08-20 11:23 135阅读 0赞

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

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

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

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

>   public class Program
> 
> \{
> 
>     static void Main(string\[\] args)
> 
>     \{
> 
>         string message = "Hello World!";  // 07/24/2010 Bob
> 
>         Console.WriteLine(message); // 07/24/2010 Bob
> 
>         message = "I am so proud of this code!"; // 07/24/2010 Bob
> 
>         Console.WriteLine(message); // 07/24/2010 Bob
> 
>     \}
> 
> \}

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

## 2.过时的程序员 ##

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

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

## 3.多此一举的程序员 ##

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

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

## 4.爱讲故事的程序员 ##

> public class Program
> 
> \{
> 
>     static void Main(string\[\] args)
> 
> \{
> 
>        /\* I discussed with Jim from Sales over coffee
> 
>         \* at the Starbucks on main street one day and he
> 
>         \* told me that Sales Reps receive commission
> 
>         \* based upon the following structure.
> 
>         \* Friday: 25%
> 
>         \* Wednesday: 15%
> 
>         \* All Other Days: 5%
> 
>         \* Did I mention that I ordered the Caramel Latte with
> 
>         \* a double shot of Espresso?
> 
>        \*/
> 
>         double price = 5.00;
> 
>         double commissionRate;
> 
>         double commission;
> 
>         if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)
> 
>         \{
> 
>             commissionRate = .25;
> 
>         \}
> 
>         else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)
> 
>         \{
> 
>             commissionRate = .15;
> 
>         \}
> 
>         else
> 
>         \{
> 
>             commissionRate = .05;
> 
>         \}
> 
>         commission = price \* commissionRate;
> 
>     \}
> 
> \}

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

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

> public class Program
> 
> \{
> 
>     static void Main(string\[\] args)
> 
>     \{
> 
>        //TODO: I need to fix this someday - 07/24/1995 Bob
> 
>        /\* I know this error message is hard coded and
> 
>         \* I am relying on a Contains function, but
> 
>         \* someday I will make this code print a
> 
>         \* meaningful error message and exit gracefully.
> 
>         \* I just don't have the time right now.
> 
>        \*/
> 
>        string message = "An error has occurred";
> 
>        if(message.Contains("error"))
> 
>        \{
> 
>            throw new Exception(message);
> 
>        \}
> 
>     \}
> 
> \}

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

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

译文链接：[http://www.codeceo.com/article/5-types-comment-we-avoid.html][http_www.codeceo.com_article_5-types-comment-we-avoid.html]

英文原文：5 Types of Programming Comments to Avoid

[http_www.codeceo.com_article_5-types-comment-we-avoid.html]: http://www.codeceo.com/article/5-types-comment-we-avoid.html