ACM通信
为什么代码注释仍然很重要
在计算机科学中，你被教导注释你的代码。当你学习一门新语言时，你要学习该语言中注释的语法。虽然编译器或解释器忽略程序中的所有注释，但注释是有价值的。然而，最近有一种观点认为注释代码是不好的，并且应该避免程序中所有的注释。在2013年的文章题为无注释:为什么注释代码仍然是一个坏主意，彼得·沃格尔继续这个讨论。
那些认为注释代码是一种坏主意认为注释增加了不必要的维护。当代码发生变化时，您还必须修改注释，以使它们与代码保持同步。他们认为程序员有责任编写非常明显的代码，这样就不需要注释了。尽管这些都是避免注释代码的有效理由，但参数过于简单和一般化。评论是必要的原因有很多:
- 不是所有的程序员都能/愿意写出非常明显的代码。初级程序员只喜欢写正确的程序。他们仍在掌握这门手艺。即使是有经验的程序员，有时也会因为懒惰而写出潦草的代码(我对此感到内疚)。程序就像指纹一样是独一无二的，因此判断代码是否明显是一个主观的要求。
- 评论太多可能会让人感到不知所措和乏味，但有些评论就像文章中的标题和副标题。它们引导你，提供背景，并传达整体意义。
- 注释不仅仅用于代码。它们可以记录重要的程序信息，如作者、日期、许可和版权细节。
- 有些编程语言很神秘。一个例子就是谷歌眼镜的编程语言。这示例程序很难破译，但它会打印出斐波那契数列。这个程序的意思你明白吗?也许可以用一种更明显的方式来编写这个程序，但是在程序顶部的一个简单的注释会快速而轻松地传达它的意思。
- 一些公司要求他们的员工注释他们的代码。谷歌具有指定如何编写注释的编程样式指南。这包括流行的编程语言，如Java，JavaScript,c++．
- 专门的注释允许这样的工具javadoc，JSDoc,apiDoc为程序自动生成专业、全面和一致的文档。
- 注释可以是未来工作的占位符。这是为大型程序创建大纲的一种有用的方法。实际上，Eclipse集成开发环境(IDE)在生成主方法时自动创建TODO注释。这是一个添加程序开始代码的提醒。
对程序进行注释有许多重要的原因。虽然评论可能是乏味的或压倒性的，但它在许多情况下是有价值的。即使您认为自己编写的代码非常明显，也要在几个月或几年后再去阅读。这对你来说还是显而易见的，还是你希望得到评论?
埃德温·托雷斯是MITRE公司的全职软件工程师，也是蒙茅斯大学计算机科学的兼职教授。在推特上关注埃德温@realEdwinTorres．
评论
丹尼斯·汉密尔顿
正如沃德·坎宁安(Ward Cunningham)所指出的，我认为评论的一个关键特征是关于叙述的。区分代码是*for*的，而不仅仅是它是什么，以及关键的假设和约束可能是什么，这是很重要的。掌握需求是什么是有价值的，代码很少能替代需求。
埃德温·托雷斯
这是一个很好的观点，谢谢你的表扬。有时候，您只需要快速浏览代码，而不需要花时间对其进行跟踪。注释在这里有帮助，假设它们是正确的。
彼得·沃格尔
嘿!谢谢你的提醒。
我们在很多事情上都是一致的——例如，我应该指出，我反对注释“在”代码中。我的反对意见不是在评论，例如，一个方法的开始。这些注释包括(如您所指出的)作者的名字、创建日期等等(不过，通常，源代码控制可以使这些工作自动化)。
我也绝对同意你的观点，方法开头的代码应该描述这个方法是“为了”什么——这个方法为什么存在或为什么被编写。这是一些非常明显的代码通常无法沟通的东西。在最好的情况下，非常明显的代码可以传达代码做什么的“如何”(尽管，方法的名称有时可以帮助说明代码的“用途”)。
我们甚至会同意需要注释加密代码。然而，我建议不应该首先通过编写注释来解决这个问题:应该首先通过编写明显的代码来解决这个问题。如果斐波那契生成器中有bug或需要增强它，清晰的代码将帮助您找到bug或以注释无法做到的方式增强代码。在这种情况下，我建议我们考虑一个评论，作为最初的程序员对下一个程序员的道歉:“我已经尽了最大努力，但是，由于各种原因，我仍然以这个不幸的代码告终。这是我能帮上忙的。”
我特别喜欢将注释作为标题和副标题来指导程序员完成代码的想法。我想，作为一名兼职技术作家，这对我特别有吸引力。当然，我建议这些评论(就像标题一样)的长度不要超过2 - 3个单词……也许，证据表明这个方法应该被重构成几个方法，它们的名称反映这些标题。但是，在很多情况下，我认为这是过分的。
事实上，我只在一个地方不同意你的观点:一个不能写出明显代码的程序员，出于某种原因，能够写出(a)明显、(b)准确、(c)完整的注释。毕竟，我们雇佣程序员是看中他们写代码的能力，而不是他们作为技术写手的能力。如果这个评论不准确……好吧，套用“编程风格的元素”，代码和它的注释提供了处理逻辑的两种描述。如果他们不同意，只有代码是正确的。此时，超出描述方法用途的代码会产生修复注释以使其与代码保持一致的维护负担。程序员已经够忙的了。
再次感谢您的提醒!
格雷厄姆·李
这是一个很好的评论理由列表，我想再加一个:对于代码的作者*您*来说显而易见的东西，对于读者*我*来说可能并不明显。如果上周您一直在处理您正在构建的特性，那么这一周您已经花了时间构建了问题领域的心智模型，并将其映射到软件系统上。我没有那种型号。开发人员应该试着同情那些理解软件的开发人员，但是对于“这个问题”还是新手，并帮助他们提高理解。
埃德温·托雷斯
Peter-谢谢你周到而全面的回复。我确实喜欢你的文章，并同意你的许多观点。我的目标是强调一些额外的评论需求。我100%同意你所说的“代码不会说谎”。此外，太多的评论会让人不知所措，让人分心。我觉得有趣的是，时至今日，关于评论的讨论仍然存在。谁会想到呢?
埃德温·托雷斯
格雷厄姆-大点。我在编程方面最早的一个经验是，改变别人的程序要比创建自己的程序难得多。如果使用有效，注释可以在这里提供帮助。
彼得·沃格尔
埃德温·托雷斯:你不知道其中的讽刺意味——在我写的所有文章中，我那篇关于为什么评论是个坏主意的文章仍然保持着吸引评论最多的记录。
CACM管理员
彼得·沃格尔:这真的很有趣。谁能想到一个无害的代码构造会引起如此多的讨论呢?
Robert Van Cleave
“即使你认为你写的代码非常明显，试着在几个月或几年后再阅读你的代码”真的深深打动了我。我不得不对几年前编写的代码进行重大修改(没有注释)，一开始完全不知所云。一旦我找到了我的“方向”，代码就很明显了，但是在一些函数的开始处添加一些注释将会有很大的帮助。
埃德温·托雷斯
罗伯特-没错。这也发生在我身上。我记得我写了一些代码又快又容易。但一年后，当我不得不修改它时，我迷路了。这是令人震惊的。和你一样，我找到了方向，做出了改变。但是最初的加速时间本可以通过一些有用的注释来避免。