前端注释规范
2019-12-10 本文已影响0人
zdlucky
注释规范
单行注释 ( // 注释说明 )
- 单独一行：//(双斜线) 与注释文字之间保留一个空格；
- 在代码后面添加注释：//(双斜线) 与代码之间保留一个空格，并且//(双斜线) 与注释文字之间保留一个空格；
- 注释代码：//(双斜线) 与代码之间保留一个空格。
示例：
// 调用了一个函数； 1)单独一行
setTitle();
const maxCount = 10; // 最大量； 2)在代码后面添加注释
// setName(); // 设置name的值； 3)注释代码
IDE快捷键：Ctrl + /
多行注释 ( /** 注释说明 */ )
- 若至少两行注释说明时，注释块第一行为
/**，最后一行为*/，其他行以*开始，并且每行*与每行注释说明和行首均保留一个空格。
示例：
/**
* 代码执行到这里后会调用 setTitle()函数
* setTitle()：设置title的值
*/
setTitle();
IDE快捷键：/** -> Enter
函数 ( 方法 ) 注释 ( /** 注释说明 */ )
- 函数(方法)注释也是多行注释的一种，但是包含了特殊的注释说明要求，如：函数功能描述、参数、返回值、作者、日期、版本、用法演示等等。
语法：
/**
* 函数说明
* @关键词
*/
/**
* 函数功能描述
*
* 具体描述一些细节（如有必要）
*
* @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使用）
文件注释 ( /* 注释说明 */ )
- 文件注释也是多行注释的一种，但是包含了特殊的注释说明要求，如：文件实现功能的描述、作者信息（姓名、邮箱等）、创建时间、最后修改者（姓名、邮箱等）、最后修改时间等等。
示例：
/*
* @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插件
基本用法：
-
文件头部注释：
在当前编辑文件中使用快捷键：Window：Ctrl + Alt + I或者Mac：Ctrl + Cmd + I，即可生成文件头部注释。 -
函数注释：
1、将光标放在函数行或者将光标放在函数上方的空白行；
2、使用快捷键：Window：Ctrl + Alt + T或者Mac：Ctrl + Cmd + T，即可生成函数注释；
3、事实上，函数注释在文件的任意位置都可生成，这里需要自己控制。
