一、目的和原则
提高代码的可读性和可维护性
如无必要,勿增注释;如有必要,尽量详尽
二、注释分类
注释共分为4种,文件头注释、单行注释、多行注释、函数注释
1. 单行注释
// 注释内容
2. 多行注释
/*
* 注释内容
* 注释内容
*/
3. 文件头注释
文件头注释建议借助vscode安装插件koroFileHeader
<!--
* @Author: 逆黄
* @UserId: 42378923
* @Create: 2019-08-09 20:56:42
* @Description: 可根据配置快速搭建详情展示模块
-->
koroFileHeader插件配置详情,该配置需配置在用户
配置,禁止配置到工作区
"fileheader.customMade": {
"Author": "逆黄",
"UserId": "42378923",
"Date": "Do not edit",
"Desctription": ""
},
"fileheader.configObj": {
"prohibitAutoAdd": [ "json", "md"],
"specialOptions": {
"Date": "Create"
}
},
4. 函数注释
函数(方法)注释也是多行注释的一种,但是包含了特殊的注释要求
语法
/**
* 函数说明
* @关键字
*/
常用注释关键字
注释名 | 语法 | 含义 | 示例 |
---|---|---|---|
@param | @param 参数名 {参数类型} 描述信息 | 描述参数的信息 | @param name {String} 传入名称 |
@return | @return {返回类型} 描述信息 | 描述返回值的信息 | @return {Boolean} true:可执行;false:不可执行 |
@author | @author 作者信息 [附属信息:如邮箱、日期] | 描述此函数作者的信息 | @author 张三 2019/01/01 |
@version | @version XX.XX.XX | 描述此函数的版本号 | @version 1.0.0 |
@example | @example 示例代码 | @example setTitle(‘测试’) |
示例
/**
* 合并Grid的行
* @param grid {Ext.Grid.Panel} 需要合并的Grid
* @param cols {Array} 需要合并列的Index(序号)数组;从0开始计数,序号也包含。
* @param isAllSome {Boolean} :是否2个tr的cols必须完成一样才能进行合并。true:完成一样;false(默认):不完全一样
* @return void
* @author 张三 2019/01/01
* @example
* _________________ _________________
* | 年龄 | 姓名 | | 年龄 | 姓名 |
* ----------------- mergeCells(grid,[0]) -----------------
* | 18 | 张三 | => | | 张三 |
* ----------------- - 18 ---------
* | 18 | 王五 | | | 王五 |
* ----------------- -----------------
*/
function mergeCells(grid, cols, isAllSome) {
// Do Something
}
三、不应当存在的注释
1. 不恰当的注释
注释应该仅用来描述有关代码和设计的技术性信息。像修改历史等信息不应出现在注释中。
2. 废弃的注释
过时、无关或错误的注释就是废弃的注释,不要写这种注释,如果发现了请尽快更新或删除,否则它会越来越远离它开始描述的代码。
3. 多余的注释
注释应该说明代码自身没有提到的事情。如果代码自身就能说明,就不要去写注释,例如:
i++; // i自增
4. 注释掉的代码
一般注释掉的代码,很可能已经与现有业务无关了,它调用的变量或函数可能已经改名,变得毫无用处。如有必要,应当注明保留原因。