ACM通信
为什么代码注释仍然很重要
在计算机科学中，你被教导注释你的代码。当你学习一门新语言时，你要学习该语言中注释的语法。虽然编译器或解释器忽略程序中的所有注释，但注释是有价值的。然而，最近有一种观点认为注释代码是不好的，并且应该避免程序中所有的注释。在2013年的文章题为无注释:为什么注释代码仍然是一个坏主意，彼得·沃格尔继续这个讨论。
那些认为注释代码是一种坏主意认为注释增加了不必要的维护。当代码发生变化时，您还必须修改注释，以使它们与代码保持同步。他们认为程序员有责任编写非常明显的代码，这样就不需要注释了。尽管这些都是避免注释代码的有效理由，但参数过于简单和一般化。评论是必要的原因有很多:
- 不是所有的程序员都能/愿意写出非常明显的代码。初级程序员只喜欢写正确的程序。他们仍在掌握这门手艺。即使是有经验的程序员，有时也会因为懒惰而写出潦草的代码(我对此感到内疚)。程序就像指纹一样是独一无二的，因此判断代码是否明显是一个主观的要求。
- 评论太多可能会让人感到不知所措和乏味，但有些评论就像文章中的标题和副标题。它们引导你，提供背景，并传达整体意义。
- 注释不仅仅用于代码。它们可以记录重要的程序信息，如作者、日期、许可和版权细节。
- 有些编程语言很神秘。一个例子就是谷歌眼镜的编程语言。这示例程序很难破译，但它会打印出斐波那契数列。这个程序的意思你明白吗?也许可以用一种更明显的方式来编写这个程序，但是在程序顶部的一个简单的注释会快速而轻松地传达它的意思。
- 一些公司要求他们的员工注释他们的代码。谷歌具有指定如何编写注释的编程样式指南。这包括流行的编程语言，如Java，JavaScript,c++．
- 专门的注释允许这样的工具javadoc，JSDoc,apiDoc为程序自动生成专业、全面和一致的文档。
- 注释可以是未来工作的占位符。这是为大型程序创建大纲的一种有用的方法。实际上，Eclipse集成开发环境(IDE)在生成主方法时自动创建TODO注释。这是一个添加程序开始代码的提醒。
对程序进行注释有许多重要的原因。虽然评论可能是乏味的或压倒性的，但它在许多情况下是有价值的。即使您认为自己编写的代码非常明显，也要在几个月或几年后再去阅读。这对你来说还是显而易见的，还是你希望得到评论?
埃德温·托雷斯是MITRE公司的全职软件工程师，也是蒙茅斯大学计算机科学的兼职教授。在推特上关注埃德温@realEdwinTorres．
评论
马克•史密斯
嗨,埃德温,
我曾经有个客户是不发表评论的。
我无法阅读客户端的代码，即使它写得非常好，这立刻就打破了纯粹的无评论的前提。
原因很简单:使用英语在整个代码库中引出代码的心理地图，这对于快速记住要在哪里进行更新至关重要。如果没有这个提示，编码器将以一种低效的方式不断地重新学习。
一般来说，我认为这是一个普遍规则的证据:一些组织宁愿增加隐性的劳动力成本，也不愿增加显式的代码大小。“把成本推到极限”，他们在军队里这么叫。
不过，我非常同意Peter的观点，即在函数/方法级别使用注释几乎在任何时候都足够了。我只需要心理地图，而不是一些可能不准确的逻辑重新哈希。
埃德温·托雷斯
马克-谢谢你的评论。你总结得很好。评论肯定有隐性的劳动力成本(低效率)，评论太多或太少。
罗德尼•贝茨
我维护了很多其他人的代码(以及我自己的代码，我不完全记得了)，我的注释原则主要来自于“什么会使它更容易”这个问题。最重要的是“它是*本地*明显的一个称职的编码员在这个语言在这里是什么”。如果是这样，注释所带来的好处微乎其微，同时仍然会出现代码混乱和不及时更新的常见问题。如果没有，就会调用注释。
所谓“本地”，我的意思是你不需要从许多遥远的地方去寻找额外的信息，尤其是在不容易直接到达相关地方的情况下。
作为一个简单的例子，当使用下标值来跟踪数组中有多少有意义的信息被占用时，有两种常见的替代不变量。下标要么指向最后一个被占用的元素，要么指向第一个未被占用的元素。你可以通过仔细阅读任何一种用法来推断出这一点，只要你确定，无论不变量是什么，它都是一贯遵循的。在进行维护时，如果你做出这种脆弱的假设，你就是在自找麻烦。如果有任何疑问，为了避免修复导致更多的破坏，您必须找到它们，并使它们一致，如果不是这样。一旦完成，在相关的声明点添加注释，以帮助任何可能再次落入这张网的可怜人。可能是你。
当所需要的信息甚至不在您正在使用的软件系统中时，这一点就更加重要了。例如，支持多目标机器/OS组合的编译器，以及必须使用多个编译器的调试器。或者只是任何文档不完善的库代码。(您能假设存在一个完全文档化的库吗?)有时您无法控制这些外部软件系统，甚至无法访问它们的源代码。
我总是修改或添加注释来记录任何难以挖掘的信息。
埃德温·托雷斯
罗德尼-谢谢你有见地的评论。你的例子证明了提供好的评论是一门艺术。我最近读到的一些评论让我怀疑它们是否不再有效。它们是“TODO”注释，我不知道功能是否已经实现。
Hugues Ferland
关于是否写评论的话题非常广泛。
注释写得很糟糕的原因有很多，从没有掌握第二语言到缺少维护。
埃德温，你觉得你能做什么?在编写代码的时候，您如何知道哪些注释将来会对您有帮助?我认为做出正确的决定不是一件容易的事。从我们编写代码的那一刻到几个月或几年之后我们需要阅读代码的时候，太多的事情可能会发生变化。
如果编写易于阅读的代码很困难，那么我认为编写结构良好的注释也同样困难，这些注释在以后不会成为障碍。另外，除了用未来读者的眼睛看之外，没有办法证明这条评论是正确的。
我也认为我们从初学者到资深程序员的转变太快了。如果我们可以配对初学者和大师来帮助学习工艺，那么也许我们可以提高我们的艺术代码和评论一样。
埃德温·托雷斯
Hugues——关于撰写和维护评论，你可能有很好的观点。我特别喜欢你关于从初学者到经验丰富的程序员的评论。我同意你的看法。这不是一夜之间就能/应该发生的事情。只有随着时间和练习，你才能成为一个高级程序员。谢谢。
史蒂夫Fouracre
使用注释还有许多其他的原因。以下是一些例子。
1.它提供了一种简单的方法，可以将代码直接链接到用敏捷中Stories编写的需求。所以让我们假设你正在使用一个流行的ALM工具，如Jira来获取需求，将代码直接链接到Story是很重要的，如果Jira Id是project -001，只需在代码中输入这个唯一的Id作为注释，现在读者可以找到负责代码的确切的Story
2.我使用Salesforce，在任何云系统中，所有东西都有限制，其中一个限制是函数声明的长度，因此这可以禁止用代码注释的替代方法。此外，代码库长度是有限的，但注释没有限制，所以较长的函数声明会导致Salesforce的第二个限制问题
3.通常功能确实需要额外的细节，而且不可能每次都简单地解释清楚，对于那些说相反的话没有构建复杂系统的人来说。我同意在适当的地方使用注释eg:不要告诉我这是一个for循环，即使我的奶奶知道;但是请务必告诉我您为什么要呼叫下游系统
史蒂夫Fouracre
关于Edwins在2018年3月07日的评论，我同意，我在写代码的时候非常努力地同时考虑不同层次的读者，这是一种只有通过时间和努力才能掌握的艺术。但我在写的时候会问自己，我写的东西有多复杂，如果我的评分超过5分(1到10)，那么它可能会得到评论。所以当我完成代码块或函数块时，我会再读一遍，这样我就能识别出任何错误，同时也能识别出我应该在哪里添加注释。当我做出这样的评价时，我会把它读给自己听，以确保它是合理的。
在我看来，这是所有优秀的开发者都应该采用的过程
史蒂夫Fouracre
我们的大脑习惯于以某种方式阅读，简单地包括空间可以加快我们的大脑处理速度(https://www.sciencedaily.com/releases/2011/11/111128171220.htm)。因此，我们的大脑处理下面第一种功能的速度远远快于第二种方法。不是因为第一种方法有更多的字符，而是因为我们的大脑如何解释数据:
//为过期、取消和清除类型的合同创建发票，将发票通过电子邮件发送给客户，并为财务创建一个任务
createInvoicesForContracts ()
createInvoicesForExpiredAndCancelledAndClearedContractsCreateFinanceTaskAndEmailCustomer ()
CACM管理员
史蒂夫——谢谢你有见地的回答。它强调了在代码中包含注释的重要性。
显示评论11 - 20的20.在总