---
description: 
globs:
alwaysApply: true
---
# 前端代码注释规则

## 代码注释规范

### 函数注释

1. **公共函数/方法注释**
   - 使用简短的注释说明函数功能
   - 注释放在函数定义上方
   - 使用中文，简洁明了地描述功能
   - 例如：
     ```typescript
     // 应用主题到DOM
     export const applyTheme = (theme: Theme) => {
       // 函数实现
     }
     ```

2. **复杂逻辑注释**
   - 对于复杂的业务逻辑，添加必要的解释性注释
   - 注释应说明代码的目的或功能，而非重复代码本身

### 组件注释

1. **组件内部注释**
   - 对于复杂组件，可在组件顶部添加简短描述
   - 对于复杂的JSX结构，可添加注释说明各部分的作用

2. **JSX注释**
   - 在JSX中使用 `{/* */}` 进行注释
   - 例如：`{/* 组件已移除 */}`

### 类型注释

1. **使用TypeScript类型系统**
   - 优先使用TypeScript类型系统而非注释来说明参数和返回值类型
   - 导入类型时使用 `import type` 语法
   - 例如：`import type { CounterState } from '@/types/components'`

2. **类型定义注释**
   - 对于复杂的类型定义，可添加简短注释说明用途

### 注释风格

1. **简洁明了**
   - 注释应简洁明了，直接说明代码的目的或功能
   - 对于简单明了的代码，不添加多余注释

2. **注释格式**
   - 单行注释使用 `//`
   - 多行注释使用 `/* */`
   - 注释与注释内容之间保留一个空格
   - 例如：`// 这是一个注释` 而非 `//这是一个注释`

3. **TODO注释**
   - 使用 `// TODO: 说明` 格式标记待完成的任务
   - TODO注释应包含具体的任务描述

4. **语言规范**
   - 注释使用中文
   - 注释应使用完整的句子，句末加标点符号
   - 专有名词和代码片段可使用英文

### 文件头注释

对于重要的文件，可在文件顶部添加文件头注释，包含：

```typescript
/**
 * 文件描述
 * 
 * @author :xxh
 * @date 创建日期
 */
```

## 总结

本规范旨在提高代码的可读性和可维护性，团队成员应遵循这些规则编写代码。规范可根据项目发展和团队反馈进行调整和完善。