expressgy
5b0b37ef78
- Prettier 配置迁移为 .prettierrc.cjs，解决 ESM/CJS 兼容问题 - 优化 package.json，补全元信息、整理依赖、完善 Bun 热更新脚本 - 归档项目初始化 PRD 与任务清单到 tasks/archive，并加日期前缀 - 同步代码风格与格式化配置，提升团队协作一致性 归档文件：tasks/archive/20240610-prd-项目初始化.md, tasks/archive/20240610-tasks-prd-项目初始化.md
112 lines
3.8 KiB
Plaintext
112 lines
3.8 KiB
Plaintext
---
|
||
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`），便于新成员快速上手。
|
||
- 注释中严禁出现密码、密钥、用户隐私等敏感信息。
|
||
- 重要模块、核心业务建议将注释内容同步到项目文档，便于知识传承和查阅。
|
||
|
||
---
|
||
|
||
**请所有开发者严格遵守以上注释规范，提升代码可读性与可维护性。** |