关于代码注释——什么是好的注释

注释这些内容

• 整体架构，高层次的观点。UML图可学习一下
• 函数的用法。输入、输出等，不需要了解具体实现即可使用。

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

• **重要的解决方案，特别是在不是很明显时。why & why not，避免之后在看到后进行重新发现新bug，又改回现有方案。

避免注释

• 描述“代码如何工作”和“代码做了什么”。
• 避免在代码已经足够简单或代码有很好的自描述性而不需要注释的情况下，还写些没必要的注释。[如果代码不够清晰以至于需要一个注释，那么或许它应该被重写。]

参考：Javascript现代教程
有用的链接：JSDoc
有用的链接：九种常见的UML图