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