前端代码注释规范

前端代码注释规范篇

最近接手别人代码，真的忍不住吐槽了！基本上代码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 **处理等待接口联调

待优化

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

临时注释，请勿删除

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

其他事项及注意点

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

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