注释之CR

JavaScript/TypeScript/Vue 项目中的注释类型及使用场景

在 JavaScript、TypeScript 和 Vue 项目中，注释是代码可读性和可维护性的重要组成部分。不同的注释类型适用于不同的场景，以下是四种常见注释类型的标准命名及推荐使用场景。

单行注释（// 注释内容）

单行注释通常用于简短的说明或临时禁用某行代码。它适合在代码行尾添加简短的解释。

// 验证手机号格式
const phoneRegex = /^1[3456789]\d{9}$/;

多行注释（/* 注释内容 */）

多行注释适用于较长的说明或临时禁用一段代码。它通常用于块级注释，可以跨越多行。

/* 
临时禁用旧版逻辑
TODO: 需重构
*/
// oldLogic();

文档注释（/** 注释内容 */）

文档注释，也称为 JSDoc 注释，用于生成 API 文档。它适合用于组件 Props、复杂方法和枚举类型的说明。

/*** 弹窗组件配置* @property {boolean} visible - 控制显示隐藏* @property {string} title - 弹窗标题*/
props: {visible: Boolean,title: String
}

/*** 提交司机招募申请* 1. 验证表单数据* 2. 组装提交参数* 3. 处理跳转逻辑* @throws {Error} 提交失败时抛出异常*/
submit() {// ...方法实现
}

/*** 渠道类型枚举* @enum {number}*/
export const ChannelType = {BD: 1,    // 百度渠道WECHAT: 2 // 微信渠道
}

模板注释（ ）

模板注释是 Vue 项目中专用的注释类型，用于在模板中添加说明。

<!-- 仅管理员可见 -->
<div v-if="isAdmin"><p>管理员内容</p>
</div>

团队协作建议

制定注释规范文档

制定统一的注释规范文档，确保团队成员遵循相同的注释标准。

# 前端注释规范## JSDoc 注释（/** ... */）
- 必须用于：组件 Props、Methods、复杂工具函数
- 必须包含：`@param` `@returns` `@throws` 等标签
- 示例：/** 格式化日期 @param {Date} date - 原始日期 @returns {string} 格式化后的字符串 */

代码审查要点

在代码审查时，确保注释的完整性和准确性。

+ /** 
+  * 获取城市配置 
+  * @param {number} cityId - 城市ID 
+  */getCityConfig(cityId) {...}- // 获取城市配置 getCityConfig(cityId) {...}

开发工具配置

在 .eslintrc.js 中添加 JSDoc 规则，确保代码中的注释符合规范。

rules: {'require-jsdoc': ['warn', {require: {FunctionDeclaration: true,MethodDefinition: true,ClassDeclaration: true}}],'valid-jsdoc': ['error', {requireParamType: true,requireReturnType: true}]
}

实际代码改造示例

以下是一个实际代码改造的示例，展示了如何将普通注释升级为 JSDoc 注释。

// 提交UT打点信息
async submitUTClue(params) {...}

改造后：

/*** 提交UT埋点信息（用户行为追踪）* @param {Object} params - 提交参数* @param {string} params.phone - 司机手机号* @param {number} params.appId - 应用ID* @param {number[]} params.joinType - 加入类型数组*/
async submitUTClue(params) {...}

术语推广技巧

在代码评审时，明确使用标准术语，确保团队成员理解和使用不同注释类型。

## 注释规范
✅ 正确用法：/** 显示加载状态 @param {boolean} isLoading - 是否加载中 */
❌ 避免使用：// 控制加载状态

通过规范命名、工具约束和代码示例的三重保障，可以确保团队高效理解和使用不同注释类型，从而提升代码质量和开发效率。