前端规范 - 前端注释规范
最近做的项目,因为看别人的代码,没有注释,看的简直头疼。代码注释,是一个程序员最基本的素养,因为写的代码,不只是给机器去执行的,还需要给自己看,给继任者看,给同项目小伙伴看注释是一个磨刀不误砍柴工的活,自己阅读起来会快;大家都写注释,互相了解起来方便如果真的开发任务很重,可以把握优先级,把核心的注释写好有的同事,觉得自己命名没问题,逻辑没问题,就可以不用写注释这样的好习惯,的确可以少些一部分注释,
[强制] 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使用规范
前端规范 - 前端注释规范
前端规范 - 前端广义安全规范
前端规范 - 前后端接口规范
前端规范 - 前端项目开发规范
更多推荐
所有评论(0)