如何真正写好代码注释 — 现代 JavaScript 教程

注释

正如咱们在 代码结构 一文所了解到的那样，注释能够是以 // 开始的单行注释，也能够是 /* ... */ 结构的多行注释。

咱们一般经过注释来描述代码怎样工做和为何这样工做。

乍一看，写注释可能很简单，但初学者在编程的时候，常常错误地使用注释。

糟糕的注释

新手倾向于使用注释来解释“代码中发生了什么”。就像这样：

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

但在好的代码中，这种“解释性”注释的数量应该是最少的。严格地说，就算没有它们，代码也应该很容易理解。

关于这一点有一个很棒的原则：“若是代码不够清晰以致于须要一个注释，那么或许它应该被重写。”

配方：分解函数

有时候，用一个函数来代替一个代码片断是更好的，就像这样：

function showPrimes(n) {
  nextPrime:
  for (let i = 2; i < n; i++) {

    // 检测 i 是不是一个质数（素数）
    for (let j = 2; j < i; j++) {
      if (i % j == 0) continue nextPrime;
    }

    alert(i);
  }
}
复制代码

更好的变体，使用一个分解出来的函数 isPrime：

function showPrimes(n) {

  for (let i = 2; i < n; i++) {
    if (!isPrime(i)) continue;

    alert(i);  
  }
}

function isPrime(n) {
  for (let i = 2; i < n; i++) {
    if (n % i == 0) return false;
  }

  return true;
}
复制代码

如今咱们能够很容易地理解代码了。函数本身就变成了一个注释。这种代码被称为 自描述型 代码。

配方：建立函数

若是咱们有一个像下面这样很长的代码块：

// 在这里咱们添加威士忌（译注：国外的一种酒）
for(let i = 0; i < 10; i++) {
  let drop = getWhiskey();
  smell(drop);
  add(drop, glass);
}

// 在这里咱们添加果汁
for(let t = 0; t < 3; t++) {
  let tomato = getTomato();
  examine(tomato);
  let juice = press(tomato);
  add(juice, glass);
}

// ...
复制代码

咱们像下面这样，将上面的代码重构为函数，可能会是一个更好的变体：

addWhiskey(glass);
addJuice(glass);

function addWhiskey(container) {
  for(let i = 0; i < 10; i++) {
    let drop = getWhiskey();
    //...
  }
}

function addJuice(container) {
  for(let t = 0; t < 3; t++) {
    let tomato = getTomato();
    //...
  }
}
复制代码

一样，函数自己就能够告诉咱们发生了什么。没有什么地方须要注释。而且分割以后代码的结构也更好了。每个函数作什么、须要什么和返回什么都很是地清晰。

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

好的注释

因此，解释性注释一般来讲都是很差的。那么哪种注释才是好的呢？

描述架构 : 对组件进行高层次的总体归纳，它们如何相互做用、各类状况下的控制流程是什么样的……简而言之 —— 代码的鸟瞰图。有一个专门用于构建代码的高层次架构图，以对代码进行解释的特殊编程语言 UML。绝对值得学习。

记录函数的参数和用法：有一个专门用于记录函数的语法 JSDoc：用法、参数和返回值。

例如：

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

这种注释能够帮助咱们理解函数的目的，而且不须要研究其内部的实现代码，就能够直接正确地使用它。

顺便说一句，不少诸如 WebStorm 这样的编辑器，均可以很好地理解和使用这些注释，来提供自动补全和一些自动化代码检查工做。

固然，也有一些像 JSDoc 3 这样的工具，能够经过注释直接生成 HTML 文档。你能够在 usejsdoc.org/ 阅读更多关于 JSDoc 的信息。

为何任务以这种方式解决：写了什么代码很重要。可是为何 不 那样写可能对于理解正在发生什么更重要。为何任务是经过这种方式解决的？代码并无给出答案。

若是有不少种方法均可以解决这个问题，为何恰恰是这一种？尤为当它不是最显而易见的那一种的时候。

没有这样的注释的话，就可能会发生下面的状况：

1. 你（或者你的同事）打开了前一段时间写的代码，看到它不是最理想的实现方式。
2. 你会想：“我当时是有多蠢啊，如今我真是太聪明了”，而后用“更显而易见且正确的”方式重写了一遍。
3. ……重写的这股冲动劲是好的。可是在重写的过程当中你发现“更显而易见”的解决方案其实是有缺陷的。你甚至依稀地想起了为何会这样，由于你好久以前就已经尝试过这样作了。因而你又还原了那个正确的实现，可是时间已经浪费了。

解决方案的注释很是的重要。它们能够帮助你以正确的方式继续开发。

代码有哪些巧妙的特性？它们被用在了什么地方：若是代码存在任何巧妙和不显而易见的方法，那绝对须要注释。

总结

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

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

注释这些内容：

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

避免注释：

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

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

本文首发于微信公众号「技术漫谈」，欢迎微信搜索关注，订阅更多精彩内容。

---

现代 JavaScript 教程：开源的现代 JavaScript 从入门到进阶的优质教程。React 官方文档推荐，与 MDN 并列的 JavaScript 学习教程。

在线免费阅读：zh.javascript.info

---

扫描下方二维码，关注微信公众号「技术漫谈」，订阅更多精彩内容。