我编写代码文档的 3 条规则

多年来，围绕注释的争论一直很多。许多人坚信“好的代码本身就应该注释”，而另一些人则倾向于在代码中加入好的注释，并认为注释是必需的。当我阅读和听到这些争论时，我注意到他们经常关注代码的“是什么”和“如何” ……即代码的功能是什么，以及它是如何实现的。但“为什么”的概念很少出现在讨论中……即为什么需要这段代码，或者为什么这样写。虽然双方都有合理的论据，但很难确定该往哪个方向走。这促使我创建了3条规则，我相信它们不仅有助于弥合双方的分歧，还能鼓励人们编写更好的代码。我想与大家分享我的3条规则，希望它们能像帮助我一样帮助你们。

规则 1：名称应该解释什么

代码中变量、参数、接口、函数、类、方法或其他内容的名称应提供足够的信息，以清晰地描述其功能或值。其他开发人员应该能够在几周或几个月后读到这些内容的名称，并准确地了解其功能或值，而无需询问、查看其他代码或阅读其他文档。如果他们需要，则应将名称更改为更清晰的名称。

为了在这里更加清晰地说明，需要注意的是，名称并不负责描述某个东西的用途。名称只负责描述这个东西的功能，或者这个东西具有的价值。

让我们看一些我亲身遇到的例子来帮助澄清这一点：

const derivatives = [];

仅凭这个名字，你能判断这个数组里会保存什么样的数据吗？显然，它保存的是一些从其他数组复制或改编而来的数据……但这些信息足够吗？试着退一步思考，如果你在编写代码时遇到这种情况，你会问自己或别人什么样的问题。

function name(user) {
  // ...
}

这里我们有一个函数，它执行与用户名称相关的操作...现在，无需阅读其他代码，或向某人询问更多上下文，您能说出这个函数的作用吗？

当我遇到这个问题时，我不得不查看更多的代码来弄清楚它的作用......在此之前，我一直在问“这会返回一个名字吗？”，“这会更新一个名字吗？”或“这会从其他数据构造一个名字吗？”

希望您能理解，以上示例的名称并不好，需要进行修改，因为它们不符合此规则的要求。您需要查看更多代码或咨询其他人，才能弄清楚它们的作用或用途。那么，哪些名称会更好呢？显然，我们可以选择很多不同的名称，但以下是几个示例：

const derivativeUsers = [];

有了这个更新的名称，我们现在可以知道这个数组将保存一些从其他数组中复制或改编的用户。无需阅读额外的代码或咨询其他人。哈哈！

function getFullName(user) {
  // ...
}

这里我们修改了函数名，以便更清楚地说明该函数的功能。通过这个简单的更新，我们现在知道该函数会返回传递给它的用户的全名。

所以，总结一下第一条规则：代码中任何命名的对象都应该清楚地描述它的作用，或者它所持有的值。这可能会让你的命名显得有些冗长，但就我个人而言，如果能让代码对你和团队来说更具可读性和可维护性，那么稍微冗长一些也是值得的。

规则 2：代码应该解释如何

事物的名称说明了它的功能，而其内部的代码则应该描述它是如何实现的。这听起来可能有点显而易见，但它带来了一些你需要考虑的事项。

为了让别人理解代码是如何工作的，它必须具有可读性和可理解性。如果没人能理解代码的工作原理，那么它的价值就大打折扣了。部分原因在于代码各个部分的命名。但其他一些因素也有助于提高代码的可读性和可理解性，例如代码的简洁性、组织结构、格式和样式等等。

这是一个庞大的话题，相关的文章、书籍和课程已经很多了，所以我就不在这里赘述了。只需要记住，编写干净的代码对于编写可读易懂的代码至关重要，它能让团队的其他成员了解某个程序是如何运作的。

另一个难题是模块化。如果某个东西很小并且只做一件事，那么理解它是如何工作的就容易得多。在你的职业生涯中，你可能以某种形式听说过这个概念。也许你熟悉单一职责原则，也就是SOLID 原则中的“S” 。如果你还不熟悉，我强烈建议你深入研究一下，因为它是软件开发领域的一个重要概念。但回到正题。如果一个函数、类、方法、组件或其他任何东西执行多项功能，代码的复杂性就会急剧增加，不仅难以识别它是如何工作的，而且随着时间的推移，维护它也变得更加困难。

因此，为了满足第二条规则，你的代码必须在几个月后你或团队的其他成员都能理解。他们应该能够轻松地识别出代码是如何实现功能的。为了做到这一点，我们必须编写干净、易读、易于理解的代码。

规则 3：评论应该解释原因

最后，当我们需要更多信息时，当我们需要理解“是什么”和“如何”之外的内容时，我们需要“为什么” ……这时注释就派上用场了。编写代码时，有时我们需要传递更多信息，例如为什么做出某个决定，为什么需要某段代码，或者一些与之相关的额外上下文。这些都应该被注释掉。

在编辑一段不太明显的代码时，可能需要考虑一些不太明显的用例。这些用例应该清晰地注释掉，这样当下一个开发人员下周、下个月甚至明年再回头查看这段代码时，他们也能考虑到这些信息，避免再次引入 bug 或破坏其他功能。

也许由于某些第三方依赖项的工作方式，需要在代码的某个特定区域执行一些“不正常”的操作。与其指望团队其他成员遇到同样的问题并不得不自己解决，不如在评论中解释一下具体情况，这样可以节省他们以后的时间（可能是几个小时甚至几天）。

理解为什么某件事要这样去做，能带来深刻的洞察力，尤其是在有多种路径可供选择，或者有间接背景影响决策的情况下。我个人认为，在代码中注释“为什么”不仅仅是“锦上添花”，而是至关重要的。它对于代码的可维护性、知识共享，以及最重要的是，对于团队其他成员的成功至关重要。

知道何时应该包含“为什么”有时很困难。大多数人，包括我自己，都忘记了我们拥有别人所不具备的知识和理解。我们一生都在假设或期望别人了解这些知识，或者轻易地理解它们……即使我们花了数月时间收集各种信息才获得这些知识。所以，当你编写下一段代码时，务必退一步思考，你假设下一位开发人员需要哪些信息才能理解它？然后，把这些内容写在注释中。

结论

好了，就是这样……保持代码文档齐全的3条简单规则。下次你编写下一个重要功能时，请记住……

1. 命名应该解释你的代码的作用。
2. 代码本身应该是可读且易于理解的，以便您和其他人可以轻松识别它是如何执行其操作的。
3. 并使用注释来提供所有额外的信息，以便每个人都知道为什么代码是这样编写的。

希望这三条规则能助你在职业生涯中不断进步！下次再见，祝你黑客生涯愉快！