前端开发注释规范

一、目的和原则

提高代码的可读性和可维护性
如无必要，勿增注释；如有必要，尽量详尽

二、注释分类

注释共分为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. 注释掉的代码

一般注释掉的代码，很可能已经与现有业务无关了，它调用的变量或函数可能已经改名，变得毫无用处。如有必要，应当注明保留原因。