Skip to main content
 首页 » 编程设计

Javascript 代码注释规范

2022年07月19日139三少

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监测到并高亮显示。多数情况是因为打字错误,所以我们可以提前修复。

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

总结

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

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

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


本文参考链接:https://blog.csdn.net/neweastsun/article/details/71516933