规范JavaScript注释

行内注释

1. 显示一个解释的评论

   // 用来显示一个解释的评论

2. 显示表达式的结果

   // -> 用来显示表达式的结果

3. 显示 console 的输出结果

   // >用来显示 console 的输出结果

示例

function test() { 
    // 测试函数 console.log('Hello World!'); // >Hello World! return 3 + 2; // ->5 } 

单行注释

示例

// 调用了一个函数；1)单独在一行 setTitle(); 

普通多行注释

示例

/* * 代码执行到这里后会调用setTitle()函数 * setTitle()：设置title的值 */ setTitle(); 

函数多行注释

函数(方法)注释也是多行注释的一种，但是包含了特殊的注释要求，参照JSDoc。

以下字段并不是全部，全部请参考JSDoc中文文档或JSDoc中文文档

/ * 合并Grid的行 * @param grid {Ext.Grid.Panel} 需要合并的Grid * @param cols {Array} 需要合并列的Index(序号)数组；从0开始计数，序号也包含。 * @param isAllSome {Boolean} ：是否2个tr的cols必须完成一样才能进行合并。true：完成一样；false(默认)：不完全一样 * @return void * @author polk6 2015/07/21 * @example * _________________ _________________ * | 年龄 | 姓名 | | 年龄 | 姓名 | * ----------------- mergeCells(grid,[0]) ----------------- * | 18 | 张三 | => | | 张三 | * ----------------- - 18 --------- * | 18 | 王五 | | | 王五 | * ----------------- ----------------- */ function mergeCells(grid: Ext.Grid.Panel, cols: Number[], isAllSome: boolean = false) { 
    // Do Something } 

文档注释

文档注释将会以预定格式出现在API文档中。它以“/\”开头，以“*/”结束，其间的每一行均以“*”开头（均与开始符的第一个“*”对齐），且注释内容与“*”间留一个空格。

文档注释必须包含一个或多个注释标签。

1. @module。声明模块

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

   / * Core模块提供最基础、最核心的接口 * @module Core */ 

2. @class。声明类

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

   @class必须搭配@constructor或@static使用，分别标记非静态类与静态类。

   / * 节点集合类 * @class NodeList * @constructor * @param {ArrayLike 
        
          } nodes 初始化节点 */ 
         

3. @method。声明函数或类方法

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

   没有指定@for时，表示此函数为全局或模块顶层函数。当函数为静态函数时，必须添加@static；当函数有参数时，必须使用@param；当函数有返回值时，必须使用@return。

   / * 返回当前集合中指定位置的元素 * @method * @for NodeList * @param {Number} [i=0] 位置下标。如果为负数，则从集合的最后一个元素开始倒数 * @return {Element} 指定元素 */ 

4. @param。声明函数参数，必须与@method搭配使用。
5. @property。声明类属性

   / * 属性说明 * @property {属性类型} 属性名 */ 

注意事项

1. 总是在单行注释符后留一个空格。

   // this is comment 

2. 总是在多行注释的结束符前留一个空格（使星号对齐）

   /* */ 

3. 如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。

   // TODO 未处理IE6-8的兼容性 function setOpacity(node, val) { 
         node.style.opacity = val; } 

1. 不要把注释写在多行注释的开始符、结束符所在行。

   /* start end */ 

   /* here is line 1 here is line 2 */ 

2. 不要编写无意义的注释。

   // 初始化value变量为0 var value = 0; 

注释示例

参数和返回值类型Type：string、boolean、number、object、array、function

基本方法块注释

如果描述不能描述清楚，添加例子来描述。

/ * @method * @param {Type} data 目标对象 * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 */ function matchedNumber(data){ 
    return '返回对象' } 

基本方法块注释-注释过长时

如果需要折行则在文本中使用
标签

/ * @method * @param {Type} data 目标对象
 * 例： * { * target:手机号 * } * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 */
 function matchedNumber(data){ 
    return '返回对象' } 

基本方法块注释-参数可选

/ * @method * @param {Type} [data] 目标对象 * 例： * { * target:手机号 * } * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 */ function matchedNumber(data){ 
    return '返回对象' } 

基本方法块注释-带默认值

/ * @method * @param {Type} data={} 目标对象 * 例： * { * target:手机号 * } * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 */ function matchedNumber(data){ 
    return '返回对象' } 

方法块注释特殊参数

/ * @method * @param {Type} data 目标对象 * @returns {Type} 运营商名称 * @desc 根据目标对象获取运营商 * @throws {string} 抛出'Error'异常 * @example * add(1, 2); // 返回3 */ function matchedNumber(data){ 
    return '返回对象' } 

如果有返回值增加@returns 如果没有省略此属性

文件注释

在文件头部增加文件注释

/ * @file LBS控制器 * @author limingle * @copyright Synway SFE * @createDate 2017-10-16 09:40:11 */ 

变量注释

将关键的变量进行特殊注释，生成到文档中

/ * @var {object} * @desc 变量定义 * @property {string} a 属性a * @property {string} b 属性b */ var foo = { 
    a: 'a', b: 'b' } 

常量注释

将关键常量进行特殊注释，生成到文档中，如果有默认值增加@default属性

/ * @constant {string} * @default #000 * @desc 常量定义 */ const COLOR_WHITE = '#fff'; 

枚举注释

/ * @enum {number} * @desc cgi常见的返回码 */ var RETCODE = { 
    / * @desc 未登录 */ NOT_LOGIN: , / * @desc 参数错误 */ PARAM_ERROR: , / * @type {string} * @desc 未知错误 */ UNKOWN_ERROR: 'unkown' } 

类的注释

/ * @class * @classdesc 这是对myClass类的描述 * @desc 这是对myClass类的构造函数的描述 */ function myClass() { 
    ... } 

/ * @class LBSControllerCom * @classdesc LBS控制类 * @desc 初始化ws */ var LBSControllerCom = Com.extends({ 
   }) 

类的属性

类的属性和变量都会生成到jsdoc文档的Member模块中，在类中使用属性标识

var LBSControllerCom = Com.extends({ 
    / * @member {string} * @desc 这样标识类的属性 */ foo1 : 'a', init: function() { 
   } }) 

webstorm的live Templates

1. desc

   / * @description: * @author: xiaokang * @time: $date$ */ 

   

2. fun

   / * @func * @desc 函数的描述 * @param {参数1的类型} 参数名 参数描述 * @param {参数1的类型} 参数名=1 默认值参数 * @param {参数1的类型} [参数名] 可选参数 * @returns {Type} 函数返回值的描述 */ 

   示例

   / * @func * @desc 这个函数用于测试 * @param {string} a 第一个参数 * @param {number} b=1 第二个参数 * @param {number} [c=2] 可选参数 * @returns {boolean} 返回值 */ function f(a, b = 1, c = 2) { 
         return true } 

   

3. method

   / * @method * @desc 根据目标对象获取运营商 * @param {参数1的类型} 参数名 参数描述 * @param {参数1的类型} 参数名=1 默认值参数 * @param {参数1的类型} [参数名] 可选参数 * @returns {Type} 函数返回值的描述 */ 

   / * @class * @classdesc 这是对myClass类的描述 */ function myClass() { 
         } / * @method * @desc myClass方法的描述 * @param {string} a - 参数a */ myClass.prototype.foo = function (a) { 
         console.log('xiaokang') return true } 

   

4. vari

   / * @var {object} * @desc 变量定义 * @property {string} a 属性a * @property {string} b 属性b */ 

   示例

   / * @var foo * @desc 变量定义 * @property {string} a 属性a * @property {string} b 属性b */ var foo = { 
         a:'a', b:'b' } 

   

文章参考

1. JavaScript 开发规范（一）： 命名与注释规范详解
2. 《Airbnb JavaScript Style Guide 中文版》
3. js/javascript代码注释规范与示例
4. Javascript注释规范
5. jsdoc
6. 小康的jsdoc