JavaScript 注释规范

Posted 2021-03-01 whm156399

　　一.注释总体原则：

　　能不注释，尽量不对代码添加注释，以减少体积。

　　如果必须要注释，则注释必须详尽，格式科学，提高代码的可读性。

　　也就是说注释并不是用来美化代码的，而是为了便于自己活着其他程序员的阅读便利性。

　　它是一种负担，但是为了团队开发等目的又是必要的。

　　二.单行注释：

　　两个斜杠//可以创建一个单行注释，斜杠后面要增加一个空格，紧接着是注释内容。

　　注释的缩进需要与所注释的代码一致，且要位于被注释代码的上面。

　　代码演示如下：

// 蚂蚁部落教程测试函数
function func() {
  // 用来存储定时器函数标识
  let flag = null;
}

　　三.多行注释：

　　/**/可以创建多行注释，也就是以"/*"开始，"*/"结束，中间是注释内容。

　　既然是多行注释，自然被注释的内容是可以换行的。

　　尽量使用单行注释替代多行注释，如果注释函数，推荐使用多行注释。

　　四.函数的注释：

　　函数是使用最为频繁的语法结构，相对较为复杂，所以良好的注释对于理解函数的功能非常有必要。

　　注释格式如下：

/*方法说明
 *@method 方法名
 *@for 所属类名
 *@param{参数类型}参数名 参数说明
 *@return {返回值类型} 返回值说明
*/

　　可以看到在注释的开始于结尾分别是/*与*/，具体的注释内容前面也带有一个星号，看起来更加整齐。

　　看一段简单的注释代码实例：

/*函数说明
 * @param {string} p1 参数1的说明
 * @param {string} p2 参数2的说明，比较长
 *     那就换行了.
 * @param {number=} p3 参数3的说明（可选）
 * @return {Object} 返回值描述
 */
 function foo(p1, p2, p3) {
  var p3 = p3 || 10;
  return {
    p1: p1,
    p2: p2,
    p3: p3
  };
}

　　五.模块注释：

　　模块注释格式如下：

/* 模块说明
* @module 模块名
*/

　　/*模块说明

　　* module模块名

　　*/

/* 类说明
 * @class 类名
 * @constructor
 */

　　由于类分为静态类与非静态类，所以 class需要与 constructor或者 static配合使用。

　　七.注释内容：

　　知道为什么需要注释，那么也就知道注释应该怎么写。

　　注释的目的是告诉阅读者不宜察觉或者不易获取到的信息，而不是一目了然的东西。

　　下面的注释就相当于废话，根本就不需要：

// 声明一个变量timer
let timer=null;

只要不是javascript盲，都能知道上面是声明一个变量，根本用不着注释。