[强制] 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 注释与代码一起更新

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

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

Logo

前往低代码交流专区

更多推荐