Swift 圣战：注释不是反模式

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

他的建议是什么呢？

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

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

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

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

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

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

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

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

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