代码质量1 注释

注释
注释可以是以 // 开始的单行注释，也可以是 /* ... */ 结构的多行注释。

“解释性”注释的数量应该是最少的。
配方：分解函数，
有时候，用一个函数来代替一个代码片段是更好的。可以很容易地理解代码

配方：创建函数
像下面这样很长的代码块，重构为函数，可能会是一个更好的变体：

好的注释
描述架构
记录函数的参数和用法
一个专门用于记录函数的语法 JSDoc：用法、参数和返回值。

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

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

注释这些内容：

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

描述“代码如何工作”和“代码做了什么”。
避免在代码已经足够简单或代码有很好的自描述性而不需要注释的情况下，还写些没必要的注释。
注释也被用于一些如 JSDoc3 等文档自动生成工具：它们读取注释然后生成 HTML 文档（或者其他格式的文档）。