多年来，我有幸与一些不起眼的公司和客户一起工作。它还让我有机会认识各种不同的程序员——每个人都有自己独特的风格。事实上，每个项目都有自己的一些独特元素。这些品质的交集让我思考我审查、更新或改进的代码。与其说是代码的实际逻辑，不如说是开发人员自己添加到代码中的注释对代码产生了相当深远的影响。这篇文章的主题是罗列一些让我印象深刻的代码注释。因为卡罗尔让我这样做。我记得查看程序代码，有一条评论是这样写的：//BecauseCarolToldMetoDoThis当我读到这行代码时，我惊呆了，“Carol是谁？”和“卡罗尔让这个开发人员做了什么？”虽然写代码的程序员两个都知道答案，但是如果是外人或者后来加的人，那么这个评论就一文不值了。当我向我的经理提到这张纸条时，他笑着说Carol显然是一个人的名字，然后就沉默了。嗯，直到现在，我还是不知道这个评论是什么意思。很大一部分被代码掩盖了在另一种情况下，我相信我将问题缩小到一个特定的类。但是打开课程，我看到大量代码用块注释掉了。疯狂的是注释代码在方法的中间。因此，我只能在阅读顶部代码后滚动几屏才能阅读其余代码。您必须记住这一点，幸运的是两者之间的时间不会太长，并且有一个指向应用程序源代码存储库的链接。心里对此很是嗤之以鼻，“提前看一大段没有注释的代码，只为看看程序是干什么用的”。当我问另一个开发人员为什么代码要这样注释和检查时，他给我的回答是“以备下次需要”。我真的很无语。只是为了好玩在基于Web的应用程序上工作时，我发现了以下javascript注释：//确保它的格式正确，因为在javascript中//like'7'or'4.3'or'derpdydo77'arevaliddates//说真的，亲自尝试一下：Date.parse('derpdydo77')这里的开发人员意识到Date.parse()方法存在问题。为了警告其他人，开发人员决定添加一个注释作为警告，同时也有一点乐趣。我只能想象这位开发人员在意识到这行不通时一定有多沮丧。道歉有时，程序员意识到他们的方法不好。很多时候，这是基于开发团队之外唯一可用的选项。于是，就有了这样的注释：//Sorryforwhatyouareabouttosee阅读代码，了解实现方法背后的情况，有助于充分理解简单的道歉注释。这有点像惊悚片中主人公在采取有计划的行动之前道歉的场景。只是围绕它编码开始作为一个白板声明，最终被移动到以下评论：//Doingthisto“notdoanythingtoeffectEricandSteve'scode”基本上，这是一个过程的入口点，代码围绕这个问题显然是由Eric和Steve引入的。但我没有任何相关背景，我也不认识Eric和Steve，我只知道任何影响他们的代码都必须被禁止。为评论而评论我们都听过这样一句话：“好的代码是自我记录的”。我完全同意这个说法，当然有些评论还是有必要的。但是，下面的注解显然不能归类为“必须”：returntrue;//returntrue这种注解显然是没有必要的，因为它很容易让我们理解返回什么。我能想到的为什么要这样注释的唯一原因是开发人员在将它们添加到实际代码之前使用注释来计算方法，然后忘记删除注释。但是如果有codereview过程，这样的评论就不会出现了。不正确的评论还记得前面的说法“好的代码是自我记录的”吗？也许最糟糕的评论是提供错误信息的评论。请看下面这个简单的例子：//AlwaysreturnsfalsepublicbooleanisActive(){returntrue;}实际上，我看到的例子远没有这么简单。然而，更糟糕的是，当您需要编写依赖于注释的复杂方法时，才意识到这样的注释是无效的。在这种情况下，没有评论总比错误的评论好。小说般的评论***我看到的一条评论是开发人员写的类似于小说般的评论：/***这是小部件方法，它将按顺序处理小部件控制器和服务中的小部件列表to*handlepre-processing(wherethewidgetinformationis*comparedag??ainsttheaveragewidgethstory),actual*processing(wherethequarterly,monthlyandweekattributes*areupdated)andallofthepost-processing(whichincludethe*analyticalmetricsandaudittableupdates)aspects.Itis*importanttorememberthewidgetrulesaroundleapyearwhere*thecosttotransferrateis7??5%adjustedtotheannualratein*ordertoaccountfortheextraday.Whenthishappens,the*processwillthrowtheLeapYearExceptionwhichwillneedtobe*validatedbytheapplicationsupportstaff.如果不这样做，*最终会导致ME-4110报告出现问题。*/我的经验法则是，任何需要那么多消息代码可能应该被分解成更小的方法。注释中的此类信息应从实际代码中移出。在上面的例子中，像流水账一样记录的业务规则和业务流程——可能会随着时间的推移而改变。结语关于如何正确写代码注释，如果单纯搜索的话，网上有很多很多。有些人甚至可能会告诉您如何尽可能避免在代码中提供注释。相反，我想分享一些我作为应用程序开发人员有幸阅读的有趣笔记。请记住，我在应用程序开发方面有20多年的编译经验-反映的是例外，而不是规则。编码愉快！翻译链接：http://www.codeceo.com/article/8-useless-code-commenting.html英文原文：CodeCommentingPatterns
