作者：Erica Sadun，原文链接，原文日期：2016/11/3
译者：Cwift；校对：walkingway；定稿：CMB

昨天，一位名叫安德鲁·华纳的开发者撰写的这篇文章引起了一些争论。文章标题“警惕注释的‘塞壬之歌’”（译者注：塞壬是希腊神话中的海妖，她的歌声极具迷惑性，会引起海啸等灾难）暗示了开发人员在自欺欺人，因为注释会降低代码的质量：

注释在腐烂。它们不会被编译，并且永远不会在运行时被执行。如果注释过时或者不正确，测试不会因此而失败，也没有用户会抱怨。和注释打交道的程序员担心“有人可能需要这个注释，或者该注释会对将来的开发带来帮助”，所以在注释真正有用之前就在代码中引入了很多注释（甚至你还得先证明它们的确是有用的）。

他的建议是什么呢？

你没有任何借口能为写注释做辩解。给这些方法一个加 try 语法，我保证你会有一个更纯净、更易维护的代码库。

我不主张用注释来补救那些糟糕的程序设计，比如差劲的命名或者有缺陷的算法。我相信注释在良好的代码实践中会发挥重要的作用——无论你的代码仅限内部使用还是作为公共 API。

正如几周前我在这篇博客上讨论过的，正在写代码的你与“未来的你”、你的团队以及你代码的读者之间存在着很大的差别。现在我不得不说一说「Swift 风格」的注释：

注释、注释、还是注释！当你需要写注释的时候，别忘了写测试。测试可以为你节省思考“我在这做什么”花费的全部时间，因为你可以看到哪里出问题了并且验证运行的结果是否符合预期。代码写的越少越好，然后把省下的时间用来更清晰地表述你所写的代码。

当然这有助于留下一个“TODO”：代码的开销在什么地方（“这里的性能真的很糟糕”），但是现在我们不得不使用它，对于当前刚好发生的错误留下一些观点，还有那些在你脑中一闪而过的想法。你理解了过去的东西，但是对于未来总是无能为力的。

修复过去的东西的开销总是很小的，因为你已经把它的完整设计装在了自己脑中。重新设计并且恢复到正常的开发速度将付出巨大的代价。

遇到那些不够明显的、棘手的或者反直觉的逻辑，注释可以向读者解释：这是故意为之。这个事件会影响那个事情；这部分数据在该阶段并未验证；这个过程由它的 delegate 负责。注释可以使你明确你的假设被应用到代码中的哪些部分，它还允许你评价代码的质量。

注释记录了你的意图。注释中可能提到之前尝试过的方法以及这些方法被放弃的原因。也可以讨论设计的决策是如何提出的——曾经探索过哪些方案，以及为什么其中的一些方案最终未被采纳。

注释使你读懂代码背后的思想。提交时的描述（Commit messages）很有帮助，但是我不认为这些描述适合记录解决方案或者意外的行为。如果代码在另一个项目中重用的话，附带的版本控制历史可能不会与源代码同步。

注释提供了一个面包屑跟踪的设计，不保存在工作记忆（working memory）中，仅仅依靠读代码或者扫描性质的测试并不能意会其中的含义。意料之外的复杂事物是你最想注释的事情之一。事实上，意外事件的注释非常重要，因为意外本质上就是一个 bug。

结构化的注释附带另外一个层次的效果：支持 API 的开销。标记（Markup）允许这一类特殊注释自动转换为高度格式化的本地文档，以方便读者进行代码审查、调试、维护和强化。

注释并不只针对不佳的设计和代码。它们记录了修正代码的过程，支持在将来进行阅读和修改。良好的注释可以减少代码的读者阅读代码所花费的精力，便于他们集中注意力去理解特定的任务，比如“我如何去增加这个特性”，而不是“这里发生了什么”。虽然良好的代码有时可以做到“自文档化”，但是这并不意味着它总是可以（或者经常可以）自文档化。

作为拜访“过去的你”的垫脚石，好的注释可以记录你当时的想法以及解释为什么你会选择这样的做事方式。无论你期望你的代码读者是多么的聪明或有洞察力，你过去的设计意图都不应该成为他们的谜题或者负担。

本文由 SwiftGG 翻译组翻译，已经获得作者翻译授权，最新文章请访问 http://swift.gg。