Cursor rule

1---
2description: writing or editing code
3globs: *.tsx, *.js, *.ts
4alwaysApply: false
5---
6# Code Commenting Guidelines
7 
8## 基本原则 Basic Principles
9- 注释应该解释**为什么**这样做，而不是**做了什么**
10- 代码即文档，仅在必要时添加注释
11- 使用清晰简洁的语言，避免冗余, English
12- 及时更新注释，确保与代码同步
13 
14## 文件头注释 File Header Comments
15```typescript
16/**
17 * @file 文件的简要描述
18 * @description 详细描述文件的功能和用途
19 * @author [作者名称]
20 * @date YYYY-MM-DD
21 */
22```
23 
24## 函数注释 Function Comments
25```typescript
26/**
27 * 函数的简要描述
28 * @description 详细描述函数的功能
29 * @param {string} param1 - 参数1的描述
30 * @param {number} param2 - 参数2的描述
31 * @returns {Promise<boolean>} 返回值的描述
32 * @throws {Error} 可能抛出的错误
33 * @example
34 * const result = await someFunction('test', 123);
35 */
36function someFunction(param1: string, param2: number): Promise<boolean> {
37  // ...
38}
39```
40 
41## 行内注释 Inline Comments
42```typescript
43// ✅ 好的注释：解释复杂的业务逻辑
44if (user.role === 'admin' && !isHoliday) {
45  // 管理员在非假日期间具有特殊权限
46  grantSpecialAccess();
47}
48 
49// ❌ 不好的注释：陈述显而易见的事实
50// 检查用户是否为管理员
51if (user.role === 'admin') {
52  // ...
53}
54```
55 
56## 待办注释 TODO Comments
57```typescript
58// TODO(github-username): 实现用户认证功能 (#123)
59// FIXME(github-username): 修复内存泄漏问题 (#456)
60// NOTE: 这里使用递归可能会导致性能问题
61```
62 
63## 类型定义注释 Type Definition Comments
64```typescript
65/**
66 * 用户配置接口
67 * @interface UserConfig
68 * @property {string} name - 用户名
69 * @property {number} age - 年龄
70 * @property {string[]} permissions - 权限列表
71 */
72interface UserConfig {
73  name: string;
74  age: number;
75  permissions: string[];
76}
77```
78 
79## 常量和枚举注释 Constants and Enum Comments
80```typescript
81/**
82 * 用户角色枚举
83 * @enum {string}
84 */
85enum UserRole {
86  /** 管理员用户 */
87  ADMIN = 'admin',
88  /** 普通用户 */
89  USER = 'user',
90  /** 访客用户 */
91  GUEST = 'guest',
92}
93 
94/** 最大重试次数 */
95const MAX_RETRY_COUNT = 3;
96```
97 
98## 弃用注释 Deprecation Comments
99```typescript
100/**
101 * @deprecated 从 v2.0.0 开始弃用，请使用 `newFunction()` 替代
102 * @see {@link newFunction}
103 */
104function oldFunction() {
105  // ...
106}
107```
108 
109## 区块注释 Section Comments
110```typescript
111//===================================
112// 初始化配置
113//===================================
114 
115//===================================
116// 工具函数
117//===================================
118 
119//===================================
120// 事件处理
121//===================================
122```
123 
124## 注释规范检查 Comment Linting
125- 使用 ESLint 的 `eslint-plugin-jsdoc` 插件检查注释格式
126- 在 CI/CD 流程中包含注释检查
127- 定期审查和更新过时的注释
128 
129## 最佳实践 Best Practices
130- 使用 JSDoc 风格的注释以获得更好的 IDE 支持
131- 为公共 API 和复杂的业务逻辑编写详细注释
132- 避免注释掉的代码，使用版本控制系统代替
133- 定期清理无用和过时的注释