[译] 代码中添加注释之好坏丑代码中添加注释之好坏丑

<b>本文讲的是[译] 代码中添加注释之好坏丑，</b>

题图是克林特 · 伊斯特伍德在《黄金三镖客》中剧照。

如果你以前听过这句话就打断我...

「好的代码自身就是文档」。

在我 20 多年以写代码为生的经历中，这是我听得最多的一句话。

陈词滥调。

像其他许多陈词滥调一样，它的核心是一个真理。但是这个真理已经被滥用，大多数说出这句话的人并不知道它的真正意思。

这句话正确吗？是的。

那是不是意味着你不应该给你的代码写注释？不是。

本文中，我们将介绍一下给代码写注释的好处、坏处和丑处。

初学者需要了解，实际上有两种不同类型的代码注释，我称之为文档注释和说明性注释。

文档注释是为了给任何可能使用你的源代码的人看的，但他们不一定会通读代码。如果你正在构建给其他开发者使用的库或框架，你需要某种形式的 API 文档。

越早从源代码中提取 API 文档，随着时间的推移，文档就越有可能变得过时或不准确。减少这种情况的一个好策略就是直接将文档嵌入代码中，之后再使用工具提取文档。

这种注释的缺点就是使你的代码非常「嘈杂」，并使得积极参与维护的人更难阅读代码。好消息是，大多是代码编辑器都支持「代码折叠」的功能，这样就可以折叠这部分注释，专注在代码上。

上图演示在 Visual Studio Code 中折叠注释。

说明性注释是给任何可能需要维护、重构或扩展你的代码的人（包括你自己）看的。

通常来说，需要说明性注释的代码散发着一种坏代码的气味，它的出现说明你的代码太复杂了。你应该尽量简化代码并删除这种注释，因为「好的代码自身就是文档」。

如果作者不花时间在使用韵脚诗装点这个稍微令人疑惑的代码，肯定可以将代码本身写的更加易读易懂。也许命名一个函数，<code>removeCurlyBraces</code> 在另一个函数 <code>sanitizeInput</code> 中调用？

不要会错意，的确有不少时候 —— 特别当你正在拼命应对繁重的工作时 —— 注入一些幽默对身心都有好处。但是当你写了一个有趣的注释来修饰不好的代码时，实际上人们不太可能稍后重构或修复代码。

你真的想为掠夺所有未来程序员阅读这首聪明的押韵诗的乐趣而负责吗？大多数的程序员会笑起来，而忽略了这段代码本身的问题。

你也会遇到多余的注释。如果代码已经足够简单明了，就不需要再添加注释了。

比如说，不要做下面这种毫无意义的事：

不过，有时候，无论你对代码本身做了什么，一个说明性注释还是需要的。

这通常发生在你需要添加一些上下文解释一个不太直观的解决方法。

以下是一个来自 Lodash 的很好的例子：

也有一些情况是 ，在经过很多思考和实验后 ，看上去天真的解决方法事实上是最好的。在这些情况下，其他的程序员会不可避免地认为他们更聪明并开始自己动手实践，最后却发现你的方法是最好的。

有时上面提到的其他程序员就是未来的你。

在这些情况下，最好的做法就是写下注释，节省所有人的时间，避免尴尬。

当然，上面的例子更多是有趣，而不是有帮助。但是你应该留下注释，警告其他人不要追求一些看似明显的「更好的解决方法」，因为你已经尝试过并否决了。当你这样做的时候，应该明确指出你尝试了哪些方案，为什么否决了这些方案。

以下是一个 JavaScript 中的简单例子：

我们介绍了好处、坏处，那么丑处呢？

有时候你会感到沮丧，特别当你为谋生而写代码时，在代码注释中你倾向于将这种沮丧的情绪发泄出来。

使用过很多的代码库后，你会见到各种各样愤世嫉俗、沮丧到黑暗或意味深长的注释。

这些可能看起来很有趣，或者在当时帮助你发泄了一部分情绪。但是当你把它们变成生产环境代码时，它们使得编写它们的程序员以及他们的雇主看起来不专业和苦大仇深似的。

不要这么做。

如果你喜欢这篇文章，请在这篇文章下方戳一下 点个赞，帮助我传播。如果你想阅读更多其他的文章，欢迎登记订阅我每周的 Dev Mastery 简报。

<b></b>

<b>原文发布时间为：2017年4月27日</b>

<b>本文来自云栖社区合作伙伴掘金，了解相关信息可以关注掘金网站。</b>