【编程思想】好的注释应该是什么样子？

通常我们写的注释大多是解释性的，比如这样：

// 这里的代码会先做这件事（……）然后做那件事（……）
// ……谁知道还有什么……
very;
complex;
code;

但良好的编码习惯是可以自带注释的，比如分解函数、创建函数。

1 分解函数

2 创建函数

同样，函数本身就可以告诉我们发生了什么。没有什么地方需要注释。并且分割之后代码的结构也更好了。每一个函数做什么、需要什么和返回什么都非常地清晰。

实际上，我们不能完全避免“解释型”注释。例如在一些复杂的算法中，会有一些出于优化的目的而做的一些巧妙的“调整”。但是通常情况下，我们应该尽可能地保持代码的简单和“自我描述”性。

什么样的注释是好注释呢？

描述架构

对组件进行高层次的整体概括，它们如何相互作用、各种情况下的控制流程是什么样的……简而言之 —— 代码的鸟瞰图。

记录函数的参数和用法

比如像这样：

/**
 * 返回 x 的 n 次幂的值。
 *
 * @param {number} x 要改变的值。
 * @param {number} n 幂数，必须是一个自然数。
 * @return {number} x 的 n 次幂的值。
 */
function pow(x, n) {
  ...
}

这种注释可以帮助我们理解函数的目的，并且不需要研究其内部的实现代码，就可以直接正确地使用它。

总结

总结

一个好的开发者的标志之一就是他的注释：它们的存在甚至它们的缺席（译注：在该注释的地方注释，在不需要注释的地方则不注释，甚至写得好的自描述函数本身就是一种注释）。

好的注释可以使我们更好地维护代码，一段时间之后依然可以更高效地回到代码高效开发。

注释这些内容：

• 整体架构，高层次的观点。
• 函数的用法。
• 重要的解决方案，特别是在不是很明显时。

避免注释：

• 描述“代码如何工作”和“代码做了什么”。
• 避免在代码已经足够简单或代码有很好的自描述性而不需要注释的情况下，还写些没必要的注释。

注释也被用于一些如 JSDoc3 等文档自动生成工具：它们读取注释然后生成 HTML 文档（或者其他格式的文档）。