你应该在每一行代码上都写注释。

你的代码会被读取多少次？

在一个成功的产品中，代码会被运行成千上万次。每次运行，解释器都会读取你的代码（请不要对我的比喻提出异议）。我们都知道，编写能在机器上高效运行的代码是值得的。你有没有想过，我的代码会被人阅读多少次呢？

因为我认为答案是很多。

大多数成功的代码会在产品中持续运行很长时间，远超你的想象。你今天访问的网站中，至少有一个网站运行着20年前的代码。虽然你的代码很可能被无数的承包商、初级开发人员和新员工解读，试图理解你的代码库；但明年最有可能翻阅你代码的人，是那个迫切想要弄明白代码功能及其运行原理的人。

你。

一直想穿越回过去，和年轻时的自己打一场？软件开发就是你的理想职业！

— EIIiot (@Loh) 2013 年 12 月 12 日

代码注释就像给自己留下一张地图。

听起来是不是很傻？为什么要地图？这地方是你自己建的！确实有点傻。但我保证，总有一天你会需要这张地图的。

代码注释基础知识

我需要向初级程序员讲解两点。

• 注释不会也不可能影响代码的性能。

实际运行代码的机器会完全忽略注释，所以我们必须用特殊字符来标记注释。在每个函数上方添加一整本小说长度的注释并不会使代码执行速度降低哪怕一皮秒。

• 长评论很容易隐藏。

刚开始使用代码编辑器时，你可能会觉得冗长的注释很烦人，需要滚动查找才能找到需要修改的代码。但一旦你对编辑器有了一定的使用经验，你应该能够“折叠”注释，这样在不需要它们的时候它们就会消失。

Bill Souror制作的 Visual Studio Code 代码折叠的精美 GIF 动画

如果你觉得可见的注释太多而感到困扰，可以搜索一下教程，学习如何在所选的代码编辑器中隐藏注释，或者默认隐藏注释！

代码注释并非代码异味。代码注释并非代码异味。

我经常看到一种观点认为，注释，尤其是长注释，是“代码异味”，也就是说它们表明你的代码可能存在问题。我完全不同意这种观点。

标准示例类似于：

var x = user.info3 // this stores the user’s age

这表明存在问题，因为最好直接给变量命名，userAge而不是x用注释。在这个人为设计的例子中，这确实是一个合理的观点，但这忽略了注释最常见的用途。注释很少仅仅解释代码中发生了什么，它们还会解释代码运行的更大上下文——也就是代码执行的“为什么”。

虽然可以重写代码，使其内部工作原理易于理解（尽管这样做并不总是方便），但却无法解释你因为代码之外的原因而以奇怪或不直观的方式做事。

//this code checks if the account creation date 
//was in 1911 since this (impossible) creation year 
//was used to indicate that these users were  
//imported from the old DB with no creation date set. 

像这样的评论解释了如果没有某种文档就永远无法理解的代码行为！

如何减少评论数量

所以，我们承认有些评论几乎是无法避免的。如果我们真的讨厌写评论，有没有什么办法可以减少写评论的次数呢？

最常见的解决方案可能是将函数拆分成更小的函数。函数内部的几行代码updateUser可能需要注释，但如果将这三行代码放在一个名为setUserScoreToZero`setUsers` 的单独函数中，则可能不需要注释，因为这段代码的作用是将用户的 `value` 设置为零，无需多言！

再说一遍，这并不能解决上面提到的问题：函数名无法解释外部因素。而且，函数名还会越来越长。代码注释很容易隐藏，但超长的函数名就只能硬着头皮用了！当然，这并不意味着命名简洁、描述性强的函数就比代码注释差。只是两者之间需要权衡取舍！

但你应该多写些评论。

标题有点标题党，抱歉，但说真的，你应该多写评论，多得多。每行都写？可能不行。以下是你可以跳过的评论：

• 变量声明（如果您设置了一个合适的变量名）
• 函数声明（再次强调，要起好名字）

就是这样！只有这两行代码可以一直省略注释，其他所有代码可能以后都需要注释。

善良至关重要

我不会在这里贴链接，但我看到的很多为编程反模式辩护的理由都归结为“如果你不能理解/使用这种风格的代码，那你根本就不应该写代码”。这种批评是否合理甚至有说服力，我暂且搁置，只想说这种想法很不友善。如果可以选择，我永远都会做出以友善为出发点的设计选择。

每次我花时间解释一些我认为人人都知道的东西时，总会收到一些感谢的评论。更棒的是，留下一些代码注释或编写一些文档，知道它们或许有一天能帮到别人——甚至未来的自己——这种感觉真的很好。这比因为“没人能看懂我的天才代码！”而抓耳挠腮要好得多。

当我们编写代码注释时，我们其实是在向未来的自己做出承诺。我们不知道这段代码是否会在未来几十年里被反复使用，还是会最终被人遗忘。但如果将来有一天，这些源代码文件再次被打开，我们一定会在那里提供帮助。以下是我们编写这段注释时的想法，希望它能对您有所帮助。祝您好运。