8个最没有意义的代码注释

多年来，我非常荣幸能和一些谦逊的公司和客户合作。我也因此有机会接触到各种不同的程序员—— 每个程序员都有自己独特的风格。事实上，每个项目本身都有一些独特的元素。

这些特质的交叉让我去思考我曾经审查、更新或提高过的程序代码。与其说是代码的实际逻辑，还不如说是开发人员自己添加到代码中的注释，对代码产生了颇为深远的影响。这篇文章的主题就是罗列一些我印象深刻的一些代码注释。

因为Carol让我这么做

我记得审查程序代码时，有一条注释是这样写的：

// Because Carol Told Me to Do This

在阅读这行代码时，我一下子就懵了，“谁是Carol？”以及“Carol让这个开发人员做什么了？”虽然写代码的程序员知道这两个答案，但换做是一个局外人或者是一个后面加进来的人，那么这条注释就毫无价值。当我和我的经理说起这条注释的时候，他哈哈大笑，只是说了句Carol明显是一个人名字之后，就无下文了。好吧，直到现在，我依然不知道这句注释究竟是什么意思。

很大一部分被代码遮挡

在另一种情况下，我相信我将问题范围缩小到了一个特定的类。但是打开这个类，我看到大量的代码被块注释掉了。让人疯狂的是，注释的代码是在方法的中间。所以，我只能在阅读完顶部的代码之后，滚动几个屏幕，才能继续阅读剩下的代码。你得牢记在心里，幸好中间间隔的时间不是太久，有到应用程序的源代码库的链接。

在我心中，我对此非常嗤之以鼻，“提前阅读没有注释的大块代码，却只是看到了程序是用来做什么的”。当我问另一名开发人员为什么代码要像这样被注释和检查的时候，他给我的回答是“万一我们下次还要用到它呢”。我真心无语。

只是为了苦中作乐

在工作于一个基于web的应用程序时，我发现了以下的JavaScript注释：

// make sure it's correctly formatted, because in javascript things  // like '7' or '4.3' or 'derpdy do 77' are valid dates  // seriously, try it out for yourself: Date.parse('derpdy do 77')

这里的开发人员意识到Date.parse（）方法存在着问题。为了警示他人，开发人员决定添加注释作为警告，同时又苦中作乐了一番。我只能想象当这个开发人员意识到此路不通时心中该是有多么的沮丧。

道歉

有些时候，程序员意识到他们的做法并不好。很多时候，这是基于开发小组之外所能做的唯一选择。于是，出现了这样的注释：

// Sorry for what you are about to see

阅读代码和理解实施方法背后的情况有助于完整地理解简单的道歉式注释。这有点像惊悚片里的英雄在采取有计划的行动之前，先道歉的那一幕。

只围绕它编码

一开始作为一个白板声明，最终被转移到以下注释：

// Doing this to "not do anything to effect Eric and Steve's code"

基本上，这是一个进程的入口点，代码围绕明显由Eric和Steve引入的问题。但是我没有任何相关的背景，也不认识Eric和Steve，我只知道任何影响了他们的代码都得禁止。

为了注释而注释

我们都听过这样一句话：“好的代码是自文档化的”。我完全同意这种说法，当然有些注释还是有必要的。但是，下面这种注释，明显不能划到“必要”的范畴中：

return true; // returns true

这种注释确明显是没有必要的，因为我们很容易理解返回什么。我能想出的关于为什么要这么注释的唯一原因就是，开发人员在添加到实际代码前，使用注释先制定出了方法，后来却忘记删掉这些注释了。但是如果有代码审查过程的话，就不会出现这样的注释。

注释不正确

还记得前面提过的“好的代码是自文档化的”这句话吗？那么，也许在所有注释中，最糟糕的就是提供了错误信息的注释。请看下面这个简单的例子：

// Always returns false  public boolean isActive() {      return true;  }

现实中我所看到的例子远远没有这么简单。然而更糟糕的是，当你需要依赖注释写一个复杂的方法时，才意识到这样的注释是无效的。在这种情况下没有注释都比错误的注释好。

小说般的注释

最后一种我见过的注释是，开发人员写的类似于小说般的注释：

/**  * This is the widget method which will process the list of  * widgets from the widget controller and service in order to  * handle pre-processing (where the widget information is  * compared against the average widget history), actual  * processing (where the quarterly, monthly and week attributes  * are updated) and all of the post-processing (which include the  * analytical metrics and audit table updates) aspects. It is  * important to remember the widget rules around leap year where  * the cost to transfer rate is 75% adjusted to the annual rate in  * order to account for the extra day. When this happens, the  * process will throw the LeapYearException which will need to be  * validated by the application support staff. Failure to do so will  * end up causing issues with the ME-4110 report.  */

我的经验法则是，任何需要那么多信息的代码或许应该分解成更小的方法。而且注释中这样的信息应该挪到实际的代码之外。而在上面的例子中，像流水账一样记录的业务规则和业务流程——却有可能随着时间而改变。

结论

关于如何正确地写好代码注释，简单地搜一下的话，网上有很多很多。有些甚至可能会告诉你如何尽可能地不在代码中提供注释。

相反，我想分享一些我有幸作为一个应用程序开发人员所读过的一些滑稽的注释。请记住，我在应用程序开发上有着20年以上的编译经验——反映了例外，而不是规则。

编码快乐！

译文链接：http://原网站已经失效/article/8-useless-code-commenting.html
英文原文：Code Commenting Patterns
翻译作者：码农网 – 小峰