JS 注释中的学问

最新推荐文章于 2023-06-30 20:33:10 发布

sSurene

最新推荐文章于 2023-06-30 20:33:10 发布

阅读量174

点赞数 1

分类专栏： JS查漏补缺文章标签： javascript 前端

本文链接：https://blog.csdn.net/sSurene/article/details/118371147

版权

JS查漏补缺专栏收录该内容

7 篇文章 0 订阅

订阅专栏

我们通常通过注释来描述代码怎样工作和为什么这样工作。

乍一看，写注释可能很简单，但初学者在编程

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

的时候，经常错误地使用注释。

// 这里的代码会先做这件事（……）然后做那件事（……）
// ……谁知道还有什么……
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) {
  ...
}

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

如果有很多种方法都可以解决这个问题，为什么偏偏是这一种？尤其当它不是最显而易见的那一种的时候。

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

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

解决方案的注释非常的重要。它们可以帮助你以正确的方式继续开发。

代码有哪些巧妙的特性？它们被用在了什么地方？

如果代码存在任何巧妙和不显而易见的方法，那绝对需要注释。

一个好的开发者的标志之一就是他的注释：它们的存在甚至它们的缺席

在该注释的地方注释，在不需要注释的地方则不注释，甚至写得好的自描述函数本身就是一种注释