---
description: 
globs: 
alwaysApply: true
---
## Cursor 代码注释规范（Code Comment Rules）

### 1. 文件头部注释
每个源文件开头应包含如下信息：
```javascript
/**
 * @file        文件简要说明
 * @author      创建者姓名（如：张三 <zhangsan@example.com>）
 * @date        创建时间（如：2024-06-01）
 * @lastEditor  最后修改人
 * @lastEditTime最后修改时间
 * @description 文件详细描述（可选）
 */
```

### 2. 函数/方法注释（JSDoc）
- 每个公开函数、类、接口都应有 JSDoc 注释
- 增加修改记录，包含修改人、修改时间、修改描述

**推荐标签：**
- `@param` 参数说明
- `@returns` 返回值说明
- `@throws` 可能抛出的异常
- `@deprecated` 弃用说明
- `@example` 使用示例
- `@modification` 修改记录（格式：修改人 修改时间 修改描述）

**示例：**
```typescript
/**
 * 计算两个数的和
 * @param a 第一个加数
 * @param b 第二个加数
 * @returns 两数之和
 * @example
 * add(1, 2) // 3
 * @modification 李四 2024-06-05 优化了参数校验
 */
function add(a: number, b: number): number {
  return a + b;
}
```

### 3. 注释类型与风格
- 单行注释：`//`，用于简短说明
- 多行注释：`/* ... */`，用于较长描述
- 文档注释（JSDoc）：`/** ... */`，用于结构化说明
- 注释应简洁明了，避免废话和重复代码内容
- 注释内容使用中文或英文均可，但需统一
- 代码变更时同步更新相关注释，避免注释与代码不符
- 不要注释掉无用代码，直接删除，必要时可通过版本管理找回

### 4. 特殊标记
- `TODO:` 需要补充或优化的内容
- `FIXME:` 需要修复的问题
- `HACK:` 临时解决方案，需后续优化

**示例：**
```javascript
// TODO: 优化此处的性能
// FIXME: 这里有边界条件未处理
// HACK: 临时绕过接口校验
```

### 5. 变量注释

- 每一个变量遵照JSDoc添加注释，携带描述、用途

参照
```ts
/**
 * MySQL数据库连接配置
 * @property {string} host     - 数据库主机地址
 * @property {number} port     - 数据库端口号
 * @property {string} user     - 数据库用户名
 * @property {string} password - 数据库密码
 * @property {string} database - 数据库名称
 */
export const dbConfig = {
  /** 数据库主机地址 */
  host: process.env.DB_HOST || 'localhost',
  /** 数据库端口号 */
  port: Number(process.env.DB_PORT) || 3306,
  /** 数据库用户名 */
  user: process.env.DB_USER || 'root',
  /** 数据库密码 */
  password: process.env.DB_PASSWORD || '',
  /** 数据库名称 */
  database: process.env.DB_NAME || 'test',
}; 
```

### 6. 规范补充建议
- 注释应随代码同步更新，避免"注释失效"或误导他人。
- 代码评审时，建议同时检查注释的准确性和完整性。
- 复杂算法、业务逻辑、边界处理、特殊依赖等务必详细注释。
- 简单、易懂的代码无需过度注释，避免注释冗余。
- 团队应约定注释统一使用中文或英文，避免混杂，提升协作效率。
- 推荐使用 ESLint、TSLint 等工具结合注释相关插件（如 eslint-plugin-jsdoc）进行注释规范自动校验。
- 可使用 IDE 插件（如 VSCode 的 JSDoc Generator）自动生成注释模板，提升效率。
- 建议在项目根目录下提供注释模板（如 `.comment-templates`），便于新成员快速上手。
- 注释中严禁出现密码、密钥、用户隐私等敏感信息。
- 重要模块、核心业务建议将注释内容同步到项目文档，便于知识传承和查阅。

---

**请所有开发者严格遵守以上注释规范，提升代码可读性与可维护性。**