Javascript 代码注释规范

javascript 代码注释规范

注释一般来说是好事情，但新手编程经常犯错误。他们写注释解释“代码是什么”，但这样解释性注释应该越少越好。
严肃地说，好的代码应该容易理解无需注释。有个极好规则：如果代码不清楚需要注释，那么也许可以重构代码。

有时最好使用函数代替一些代码片段，如下：

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

        // check if i is a prime number
        for (let j = 2; j < i; j++) {
          if (i % j == 0) continue nextPrime;
        }

        alert(i);
      }
    }

应该重构为：

    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;
    }

现在，我们没有注释也能很容易理解代码，因为代码本身是自描述的。

如何我们有段长代码段，如下：

    // here we add whiskey
    for(let i = 0; i < 10; i++) {
      let drop = getWhiskey();
      smell(drop);
      add(drop, glass);
    }

    // here we add juice
    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指定的语法格式：用法，参数，返回值.
举例：

    /**
     * Returns x raised to the n-th power.
     *
     * @param {number} x The number to raise.
     * @param {number} n The power, must be a natural number.
     * @return {number} x raised to the n-th power.
     */
    function pow(x, n) {
      ...
    }

这样的注释无需看它的代码，很容易理解函数的意图以及正确的使用方式。

顺便说下，许多编辑器如WebStorm可以理解这样格式，提供自动完成和自动代码检查。
也有工具如JSDOC3，可以从注释中生成HTML文档，你可以了解更多信息关于JSDOC.

为什么任务使用这种方式解决
写什么很重要，但对理解“代码是什么”不写什么更重要。为什么任务正好用这种方式解决，代码没有答案。

如果有多种方式解决任务，为什么是这种？特别当它不是最明显的一个。

下面场景中没有这样的注释是可能的：

• 1.你（或你的同事）贷款很久以前的代码，看到它可以调优。
• 2.你想：过去我多么愚笨，现在我很聪明。使用更明显和正确的方式重构。
• 3.勇于重写是好的。但这过程中，你发现更明显的解决方案实际很缺乏。甚至你模糊记得为什么，因为在很久以前你已经尝试过。然后你恢复原状，但浪费了很多时间。

说明解决方案的注释很重要，可以帮助继续以正确的方式开发。

代码有任何微妙的特性？在哪里使用？
如果代码有任何微妙特性和不明显的内容，则非常值得添加注释。

代码风格指南

代码风格指南包括如何写代码的一般规则，如使用那种引号，缩进多个空格，在哪换行等，很多细节。
总的来说，团队成员使用相同的风格，代码会统一，无论团队中谁写的代码，风格仍然一致。

当然，团队可以设想自己的代码风格，但当下，没有必要。业界有很多中代码风格，容易采纳使用：

举例：

• Google JavaScript Style Guide
• Airbnb JavaScript Style Guide
• Idiomatic.JS
• ……

后面也有博文说明代码风格，供参考。关于自动样式检查，下面开始描述。

自动风格检查-linter

有自动风格检查工具，linter.多数知名的是：

• JSLint -linter中最早的。
• JSHint -比JSLint有更多的设置。
• ESLint -最新的linter。

建议使用ESLint。大多数linter和编辑环境集成。只需要在编辑器中启用并配置样式风格。举例，ESLint的全局配置如下：

1.安装nodejs
2.安装ESLint，通过命令行 npm install -g eslint
3.创建.eslintrc全局配置文件，在javascript项目的根目录中。

示例：

    {
      "extends": "eslint:recommended",
      "env": {
        "browser": true,
        "node": true,
        "es6": true
      },
      "rules": {
        "no-console": 0,
      },
      "indent": 2
    }

这里直接使用”extends”表示我们基于eslint的推荐设置，然后定义我们自己的规范。
可能你会下载风格规范然后扩展，具体规范描述地址为： http://eslint.org/docs/user-guide/getting-started

使用linter也有很好的附带效果，捕获打字错误。举例，当有一个未定义变量被访问时，linter监测到并高亮显示。多数情况是因为打字错误，所以我们可以提前修复。

因为，即使你不关心样式，我也推荐你使用。

总结

好的开发人员标志之一就是他的注释。好的注释可以很好的维护代码，即使过了很长时间也可以更有效了解代码特性并使用。

代码风格也很重要，特别在团队中开发。当其他人看你代码，好的风格影响很大。好代码应该容易读和理解。

关于代码风格指南，如引号、空格等，我们应该记住他们仅为了让代码更好，易读易维护。