前端注释规范

注释规范

单行注释 ( // 注释说明 )

  1. 单独一行://(双斜线) 与注释文字之间保留一个空格;
  2. 在代码后面添加注释://(双斜线) 与代码之间保留一个空格,并且//(双斜线) 与注释文字之间保留一个空格;
  3. 注释代码://(双斜线) 与代码之间保留一个空格。
示例:
// 调用了一个函数;  1)单独一行
setTitle();

const maxCount = 10; // 最大量;  2)在代码后面添加注释

// setName(); // 设置name的值;  3)注释代码
IDE快捷键:Ctrl + /

多行注释 ( /** 注释说明 */ )

  1. 至少两行注释说明时,注释块第一行为/**,最后一行为*/,其他行以*开始,并且每行*与每行注释说明和行首均保留一个空格。
示例:
/**
 * 代码执行到这里后会调用 setTitle()函数
 * setTitle():设置title的值
 */
setTitle();
IDE快捷键:/** -> Enter

函数 ( 方法 ) 注释 ( /** 注释说明 */ )

  1. 函数(方法)注释也是多行注释的一种,但是包含了特殊的注释说明要求,如:函数功能描述、参数、返回值、作者、日期、版本、用法演示等等。
语法:
/**
 * 函数说明
 * @关键词
 */

/**
 * 函数功能描述
 * 
 * 具体描述一些细节(如有必要)
 * 
 * @param    {string}  address    地址
 * @param    {array}   userList   用户列表数组
 * @param    {string}  payType   支付方式( '1'-微信、'2'-支付宝 )
 * @returns  void
 *
 * @author   zd
 * @date     2019-12-11
 * @version  1.0.2
 */
常用注释关键字:(只列出一部分,并不是全部,可通过输入@进行选择)
注释名 语法 含义 示例
@param @param {参数类型} 参数名 描述信息 描述参数的信息 @param {String} name 名称
@return @return {返回值类型} 返回数据 描述信息 描述返回值的信息 @return {Boolean} isShow 是否显示( true-显示、false-不显示 )
@author @author 作者信息 [附属信息:如邮箱、日期] 描述此函数作者的信息 @author 张三 2015/07/21
@version @version XX.XX.XX 描述此函数的版本号 @version 1.0.3
@example @example 示例代码 演示函数的使用 @example setTitle('测试')
示例:
/**
 * 合并Grid的行
 * @param {Ext.Grid.Panel} grid 需要合并的Grid
 * @param {Array} cols 需要合并列的Index(序号)数组;从0开始计数,序号也包含。
 * @param {Boolean} isAllSome 是否2个tr的cols必须完全一样才能进行合并( true-完全一样、false(默认)-不完全一样 )
 * @return void
 * @author zd 2019/12/11
 * @example
 * _________________                             _________________
 * |  年龄 |  姓名 |                              |  年龄 |  姓名 |
 * -----------------      mergeCells(grid, [0])   -----------------
 * |  18   |  张三 |              =>             |       |  张三 |
 * -----------------                             -  18   ---------
 * |  18   |  王五 |                             |       |  王五 |
 * -----------------                             -----------------
 */
function mergeCells(grid, cols, isAllSome) {
    // Do Something
}
IDE快捷键:Ctrl + Alt + T(需配合 VS Code 注释插件koroFileHeader使用)

文件注释 ( /* 注释说明 */ )

  1. 文件注释也是多行注释的一种,但是包含了特殊的注释说明要求,如:文件实现功能的描述、作者信息(姓名、邮箱等)、创建时间、最后修改者(姓名、邮箱等)、最后修改时间等等。
示例:
/*
 * @Description: **请编辑描述内容**
 * @Author: zd
 * @Date: 2019-12-11 17:00:00
 * @LastEditors: David
 * @LastEditTime: 2019-12-11 17:08:00
 */
IDE快捷键:Ctrl + Alt + I(需配合 VS Code 注释插件koroFileHeader使用)

更多注释内容,可参考JSDOC :http://usejsdoc.org


VS Code 注释插件推荐

VS Code 注释推荐使用koroFileHeader插件

一个读取用户自定义模板,通过快捷键添加文件头部注释、在光标处添加函数注释的VS Code插件

基本用法:
  • 文件头部注释:
    在当前编辑文件中使用快捷键:WindowCtrl + Alt + I 或者 MacCtrl + Cmd + I,即可生成文件头部注释。

  • 函数注释:
    1、将光标放在函数行或者将光标放在函数上方的空白行;
    2、使用快捷键:WindowCtrl + Alt + T 或者 MacCtrl + Cmd + T,即可生成函数注释;
    3、事实上,函数注释在文件的任意位置都可生成,这里需要自己控制。

更多用法:

推荐阅读更多精彩内容

  • 可以通过设置编辑器来设置出一致的注释模式。 1. HTML注释 模块注释 区块注释 2. CSS注释 组件块和子组...
    椰果粒阅读 3,331评论 0 2
  • JavaScript编码规范 1 前言 2 代码风格 2.1 文件 2.2 结构 2.2.1 缩进 2.2.2 空...
    江湖相望知冷暖阅读 176评论 0 0
  • JavaScript编码规范 1 前言 [2 代码风格] [2.1 文件] [2.2 结构] [2.2.1 缩进]...
    忆飞阅读 853评论 1 2
  • JavaScript编码规范 1 前言 2 代码风格 2.1 文件 2.2 结构 2.2.1 缩进 2.2.2 空...
    HARRISKING阅读 277评论 0 0
  • JavaScript编码规范 1 前言 JavaScript 在百度一直有着广泛的应用,特别是在浏览器端的行为管理...
    Top_Chenxi阅读 218评论 1 2