前端规范 - 前端注释规范

[强制] 1 一定要注释！

最近做的项目，因为看别人的代码，没有注释，看的简直头疼。
代码注释，是一个程序员最基本的素养，因为写的代码，不只是给机器去执行的，还需要给自己看，给继任者看，给同项目小伙伴看

1.1 不能因为开发任务重而不写注释

注释是一个磨刀不误砍柴工的活，自己阅读起来会快；大家都写注释，互相了解起来方便
如果真的开发任务很重，可以把握优先级，把核心的注释写好

1.2 不能觉得自己开发习惯好而不写注释

有的同事，觉得自己命名没问题，逻辑没问题，就可以不用写注释
这样的好习惯，的确可以少些一部分注释，不过

• 命名好，不代表大家都能看的懂
  你百度翻译到了专业的命名，换一个人读的话，还需要去百度翻译一下词义
• 逻辑写的好，不代表大家理解的快
  逻辑写的清晰，但是如果是个复杂的模块的话，再清晰的代码逻辑，在代码量的加成上，都会提升理解上的难度

所以没有理由不写注释，注释写的好，不见得是好程序员；注释写不好，肯定不是好程序员！

[强制] 2 必须有注释的地方

• 业务模块的顶部注释
• 复杂模块代码
• 上下游影响比较大的代码
• 单纯读名字看不懂意思的方法/变量/常量名字
• 影响较大的全局代码
• 比较反常的处理，例如某产品特殊要求的逻辑
• 专门fix某不常见bug的注释
• 统一管理的接口api、上下游依赖的各个链接/参数

3 可以不加注释的地方

• 业内公用的逻辑，比如vue react的生命周期，常用内置方法
• 项目开发词典里面规范的常用方法
• 命名+逻辑都很简单的方法，如 getUserInfo

4 业务模块顶部注释

单vue文件、js文件、css文件，均可以在头部打注释，全局介绍当前模块的作用
必须有的字段有 Author Date Description 等

• 单vue文件顶部注释

  <!--
   * @Author: zhangsan
   * @Date: 2022-02-19 11:21:21
   * @LastEditors: lisi
   * @Description: XXX模块首页
  -->
  <template>
  ...
  

• js文件顶部注释

  /**
   * @Author: zhangsan
   * @Date: 2022-03-06 15:03:33
   * @Description: 打补丁，处理xx模块的xx逻辑
   */
   import utils from '@/utils'
   ...
  

5 方法内、外，单行、多行注释

5.1 工具类方法，上方多行注释

便于知晓入参、出参的内容，便于typeScript的悬浮展示方法引用
使用JsDoc注释规范
在vscode中，写完了代码逻辑，在函数上方输入 /** */ 后 回车，即可得注释模板

/**
 * @description 日期格式化
 * @param {string} fmt YYYY-mm-dd YYYY-mm-dd HH:MM:SS
 * @param {object} date 日期对象
 * @returns {String} 日期格式化后数据
 */
export function dateFormat (fmt, date) {
...

5.2 简单方法，可以上方单行注释

能够节省点代码行数

// 查询部件树
getBjTree () {
...    

5.3 方法内的单行注释，可以代码后同行展示的

• object类对象里面数据说明的，如vue中data字段的说明
• 简单的变量定义、方法调用

 data () {
    return {
      listDialogVisible: false, // 单个属性编辑弹窗可见性
      priceRuleListErrorIds: [], // 错误单价公式id集合
      ...
    }
 }

[强制] 6 特殊处理的代码，一定要注释

6.1 特殊处理的全局代码

不仅要注释好，更需要跟团队小伙伴周知

// main.js ...
// 修改表单标签的后缀
ELEMENT.Form.props.labelSuffix.default = ''
// 为表格加上border
ELEMENT.Table.props.border.default = true
// dialog默认点击背景不关闭
ELEMENT.Dialog.props.closeOnClickModal.default = false
// ...

6.2 比较反常的处理

比如产品给我们提出一个业务场景，与常用的逻辑不太符号，但的确是用户的真实要求
这个时候，我们打上注释，一是为了日后我们回顾这段代码时，知道为什么会写违背逻辑的代码，二算是留下与产品沟通的证据

/**
 * xx特殊处理，为了使用户可以获得xx效果。xx产品于2021.11.03提出。
 */

神仙也难看懂的特殊处理

...
// 处理权限返回
bandleAuthFn()
bandleAuthFn()
...

如上面代码，完全相同的两句调用，看似bug，其实为权限特殊要求
所以这个地方，就需要额外注释其特殊性

7 特殊注释

7.1 TODO

在业务开发过程中，标记后面需要将改模块完善，并且在后续完善代码之后，把TODO字眼删掉

7.2 待优化

逻辑可用，不过存有优化的空间，业务昨晚之后回头优化该部分代码

7.3 临时注释，请勿删除

注释掉一段代码逻辑，但可能后面会启用这个逻辑，这个时候需要打上备注，避免别人review代码的时候删掉

8 其他事项

8.1 言简意赅 vs 十分详细

• 对于容易理解的代码，可以简单的一句话带过
• 对于复杂的业务代码，流程比较长的方法，仅在方法名称上注释是远远不够的，注释需要多多益善，

8.2 注释与代码一起更新

代码逻辑变了，注释还是旧的，那就成了毒注释，很容易误导别人

欢迎查阅本专栏其余前端相关规范

• html css js 三驾马车 3篇
  前端规范 - html规范
  前端规范 - css规范
  前端规范 - js开发规范

• 开发框架类 1篇
  前端规范 - vue开发规范

• 开发实践类 5篇
  前端规范 - git使用规范
  前端规范 - 前端注释规范
  前端规范 - 前端广义安全规范
  前端规范 - 前后端接口规范
  前端规范 - 前端项目开发规范