前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >规范JavaScript注释

规范JavaScript注释

作者头像
Dreamy.TZK
发布2020-06-28 11:35:03
12.7K0
发布2020-06-28 11:35:03
举报
文章被收录于专栏:小康的自留地

行内注释

  1. 显示一个解释的评论 // 用来显示一个解释的评论
  2. 显示表达式的结果 // -> 用来显示表达式的结果
  3. 显示 console 的输出结果 // >用来显示 console 的输出结果

示例

代码语言:javascript
复制
function test() { // 测试函数
    console.log('Hello World!'); // >Hello World!
    return 3 + 2; // ->5
}

//(双斜线)与代码之间保留一个空格,并且//(双斜线)与注释文字之间保留一个空格。

单行注释

示例

代码语言:javascript
复制
// 调用了一个函数;1)单独在一行
setTitle();

单独一行://(双斜线)与注释文字之间保留一个空格。

普通多行注释

示例

代码语言:javascript
复制
/*
* 代码执行到这里后会调用setTitle()函数
* setTitle():设置title的值
*/
setTitle();

若开始/*和结束*/都在一行,推荐采用单行注释。若至少三行注释时,第一行为/*,最后行为*/,其他行以*开始,并且注释文字与*保留一个空格。

函数多行注释

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

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

常用注释关键字

注释名

语法

含义

示例

@param

@param 参数名 {参数类型} 描述信息

描述参数的信息

@param name {String} 传入名称

@return

@return {返回类型} 描述信息

描述返回值的信息

@return {Boolean} true:可执行;false:不可执行

@author

@author 作者信息 [附属信息:如邮箱、日期]

描述此函数作者的信息

@author 张三 2015/07/21

@version

@version XX.XX.XX

描述此函数的版本号

@version 1.0.3

@example

@example 示例代码

演示函数的使用

@example setTitle(‘测试’)

代码语言:javascript
复制
/**
* 合并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<Element>} 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

基本方法块注释

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

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

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

如果需要折行则在文本中使用<br/>标签

代码语言:javascript
复制
/**
 * @method
 * @param {Type} data 目标对象<br/>
 * 例:
 *  {
 *      target:手机号
 *  }
 * @returns {Type} 运营商名称
 * @desc 根据目标对象获取运营商
 */
function matchedNumber(data){
    return '返回对象'
}

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

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

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

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

方法块注释特殊参数

如果描述不能描述清楚,添加例子来描述。 如果方法中有异常处理,标记异常处理注释

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

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

文件注释

在文件头部增加文件注释

代码语言:javascript
复制
/**
 * @file LBS控制器
 * @author limingle
 * @copyright Synway SFE
 * @createDate 2017-10-16 09:40:11
 */

变量注释

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

代码语言:javascript
复制
/**
 * @var {object}
 * @desc 变量定义
 * @property {string} a 属性a
 * @property {string} b 属性b
 */
var foo = {
    a: 'a',
    b: 'b'
}

常量注释

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

代码语言:javascript
复制
/**
 * @constant {string}
 * @default #000
 * @desc 常量定义
 */
const COLOR_WHITE = '#fff';

枚举注释

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

类的注释

默认情况先一个function就是一个类,ES6中使用Class来表示一个类 我们项目中使用class.js来实现类,在我们项目中使用类注释时需要在@class后边增加类名,不然jsdoc无法自动识别类名

代码语言:javascript
复制
/**
 * @class
 * @classdesc 这是对myClass类的描述
 * @desc 这是对myClass类的构造函数的描述
 */
function myClass() {
    ...
}
代码语言:javascript
复制
/**
 * @class LBSControllerCom
 * @classdesc LBS控制类
 * @desc 初始化ws
 */
var LBSControllerCom = Com.extends({})

类的属性

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

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

webstorm的live Templates

  1. desc12345/** * @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 }
image-20200625175556046
image-20200625175556046
  1. 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 }
image-20200625175943579
image-20200625175943579
  1. 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' }
image-20200625175042098
image-20200625175042098

文章参考

  1. JavaScript 开发规范(一): 命名与注释规范详解
  2. 《Airbnb JavaScript Style Guide 中文版》
  3. js/javascript代码注释规范与示例
  4. Javascript注释规范
  5. jsdoc
  6. 小康的jsdoc
本文参与 腾讯云自媒体同步曝光计划,分享自作者个人站点/博客。
原始发表:2020-06-25,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 作者个人站点/博客 前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 行内注释
  • 单行注释
  • 普通多行注释
  • 函数多行注释
  • 文档注释
  • 注意事项
  • 注释示例
    • 基本方法块注释
      • 基本方法块注释-注释过长时
        • 基本方法块注释-参数可选
          • 基本方法块注释-带默认值
            • 方法块注释特殊参数
              • 文件注释
                • 变量注释
                  • 常量注释
                    • 枚举注释
                      • 类的注释
                        • 类的属性
                        • webstorm的live Templates
                        • 文章参考
                        领券
                        问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档