多年来，我非常荣幸能和一些谦逊的公司和客户合作我也因此有机会接触到各种不同的程序员—— 每个程序员都有自己独特的风格事实上，每个项目本身都有一些独特的元素这些特质的交叉让我去思考我曾经审查、更新或提高过的程序代码。
与其说是代码的实际逻辑，还不如说是开发人员自己添加到代码中的注释，对代码产生了颇为深远的影响这篇文章的主题就是罗列一些我印象深刻的一些代码注释。
因为Carol让我这么做我记得审查程序代码时，有一条注释是这样写的：// Because Carol Told Me to Do This在阅读这行代码时，我一下子就懵了，“谁是Carol？”以及“Carol让这个开发人员做什么了？”虽然写代码的程序员知道这两个答案，但换做是一个局外人或者是一个后面加进来的人，那么这条注释就毫无价值。
当我和我的经理说起这条注释的时候，他哈哈大笑，只是说了句Carol明显是一个人名字之后，就无下文了好吧，直到现在，我依然不知道这句注释究竟是什么意思很大一部分被代码遮挡在另一种情况下，我相信我将问题范围缩小到了一个特定的类。
但是打开这个类，我看到大量的代码被块注释掉了让人疯狂的是，注释的代码是在方法的中间所以，我只能在阅读完顶部的代码之后，滚动几个屏幕，才能继续阅读剩下的代码你得牢记在心里，幸好中间间隔的时间不是太久，有到应用程序的源代码库的链接。
在我心中，我对此非常嗤之以鼻，“提前阅读没有注释的大块代码，却只是看到了程序是用来做什么的”当我问另一名开发人员为什么代码要像这样被注释和检查的时候，他给我的回答是“万一我们下次还要用到它呢”我真心无语。
只是为了苦中作乐在工作于一个基于web的应用程序时，我发现了以下的JavaScript注释：// make sure its 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 Steves 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://www.codeceo.com/article/8-useless-code-commenting.html英文原文：Code Commenting Patterns翻译作者：码农网 – 小峰
长按二维码关注
看精选文章，关注后，后台回复：精选看demo，关注后，后台回复：demo
亲爱的读者们，感谢您花时间阅读本文。如果您对本文有任何疑问或建议，请随时联系我。我非常乐意与您交流。
发表评论:
◎欢迎参与讨论，请在这里发表您的看法、交流您的观点。