前端代码注释规范

前端代码注释规范篇

最近接手别人代码,真的忍不住吐槽了!基本上代码0注释,变量,方法作用全靠猜!哇,真的心态炸裂。有想把前作者拽过来手撕的冲动!

好,进入正题。我们写代码一定要加注释! js虽然对代码规范要求没那么严格,但是也要注意的,不然代码写的越来越多,可维护性就会变得越来越差。自己写的代码修改起来都要重读一遍,更何况是同事或者未来交接工作呢?简直是害人不利己…… 建议大家都养成清晰注释的好习惯!

1.不能因为开发任务重而不写注释。

注释是一个磨刀不误砍柴工的活,只是顺手的事,自己阅读起来会快;大家都写注释,互相了解起来方便
如果真的开发任务很重,可以把握优先级,把核心的注释写好
注释写的好,不一定是好程序员,但是注释写的不好,肯定不是好程序员!

2.不能因为觉得自己开发习惯好就不写注释

有的程序员觉得自己命名规范,开发习惯好,逻辑也清晰,封装结构完整就不写注释。但是你命名好不代表大家都能看得懂,你的封装思路也不代表大家的封装思路。
如果是复杂的模块,再清晰地代码结构,都会提升理解上的难度。勿自以为是,造成二次开发难度和复用性难度。

3.必须加注释的地方

  • 业务模块的顶部注释
  • 复杂模块的逻辑
  • 上下游影响比较大的代码
  • 单纯靠名字不能理解意思或用法的方法、变量、常量名。
  • 影响较大的全局代码以及修改全局代码、样式等,标注修改用途和影响范围
  • 比较反常的处理,例如对某公司,或某业务要求的特殊逻辑
  • 专门fix某个不常见的bug,需要添加注释
  • 统一管理的接口api,上下游依赖的各个链接、参数等

4.可以不加注释的地方

  • 业内公用逻辑,比如vue生命周期,常用内置方法,浏览器方法等
  • 命名+逻辑简单的方法,例如getData,getUserInfo……

5.模块、组件顶部注释

vue组件顶部注释

    
	<templte>

js文件顶部注释

    /**
     * @description:
     * @author: hanaynshuo
     * @param {} num
     * @return {}
     * @date 2023-01-17 11:33:00
    */
    import { getName } from '@/api'

5.方法内外的单行、多行注释

复杂方法、工具类封装方法的多行注释

需要注释入参、出参、方法描述的多行注释

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

简单方法,使用单行注释

// 控件颜色改变触发事件
handelColorChange() {

变量行内注释

data() {
	return {
		btnVisible: false, // 确定按钮是否显示标识
	}
}

6. 特殊的处理逻辑、代码,必须添加注释

全局代码修改,要注释好并让开发组同事周知。

	// index.scss文件全局修改.con的overflow属性,旨在项目页面超出时使用滚动条显示
	.con{
		overflow-y: auto

7. 修改特定bug,业务特定的逻辑等,标明原因或bug的id

	/**
	 * xx特殊处理,为了让用户可以修改浏览器标签页icon。xx产品于***提出。
	 */
	/**
	 * bug修改:bugID:451854641888746
	 * 影响范围:***
	 * 原因及修改项:***
	 */

错误注释案例

	// 处理icon逻辑
	handleChangeIcon()

如上代码,在实际开发当中,可能这一个问题,找原因就要耗时半天一天的时间。把思路引向了模棱两可的错误方向。没有标明代码的特殊性。

8.其他特殊注释

TODO

在vscode上结合插件 TODO tree一起使用,标记还未开发完或未完善的代码,可以实现未完成功能点的统一管理。

// TODO **处理等待接口联调

待优化

由于开发时间限制,暂时可用,但是有优化空间的代码。

临时注释,请勿删除

一些临时注释掉的代码逻辑,后期开发可能会用到,标注注释防止别人优化代码删掉注释。

其他事项及注意点

  • 对于复杂的业务代码,注释要多多益善,包括方法的完整多行注释,还要添加内部的单行注释。
  • 注释要跟随开发随时更新,防止导致代码与处理逻辑无法对应的问题。也便成了毒注释误导其他开发者。

以上仅为个人总结的开发规范,若有不足请指出。

你可能感兴趣的:(前端知识,前端,vue.js,javascript,代码规范)