# 注释写作风格指南

本指南规范注释的写作风格和语言规范，确保注释专业且一致。

## 目录

- [语气标准](#语气标准)
- [语言与语法规范](#语言与语法规范)
- [示例改进](#示例改进)

---

## 语气标准

### 视角与时态

- **称呼**：以"您"称呼读者
- **语态**：使用主动语态
- **时态**：使用现在时（例如"函数返回..."而非"函数将返回..."）

### 语气要求

- **专业**：避免口语化和非正式表达
- **友好**：保持帮助性的语气，但不冗长
- **直接**：开门见山，避免绕圈子

### 清晰度要求

- **词汇**：使用简单词汇，避免过度使用专业术语
- **俚语**：避免俚语和口语表达
- **营销用语**：避免宣传性和夸张性语言

### 要求层级

明确区分不同层级的指令：

| 层级     | 用词               | 说明                           |
| -------- | ------------------ | ------------------------------ |
| 强制要求 | **必须**、**严禁** | 必须遵守的规则，违反会导致错误 |
| 强烈建议 | **推荐**、**建议** | 推荐的最佳实践                 |
| 可选建议 | **可以**、**考虑** | 可根据情况选择的建议           |

**避免使用**："应当"、"宜"等模糊表述。

### 措辞选择

| 避免     | 推荐     |
| -------- | -------- |
| 请       | （省略） |
| 允许你   | 可以     |
| 允许您   | 您可以   |
| 函数认为 | 函数检查 |
| 数组包含 | 数组有   |

**可以使用缩写**：不要、它是、它有、它会等。

---

## 语言与语法规范

### 缩写使用

| 避免   | 推荐      |
| ------ | --------- |
| e.g.   | 例如      |
| i.e.   | 即        |
| etc.   | 等        |
| vs.    | 与...对比 |
| et al. | 等人      |

### 标点符号

- **序列逗号**：在列表中使用逗号分隔（如"a、b、c"）
- **中文引号**：使用 `""` 而非 `""`
- **英文引号**：使用 `""` 而非 ''

### 日期格式

使用明确格式，例如：

- ✅ "2026年1月22日"
- ✅ "January 22, 2026"
- ❌ "2026/1/22"
- ❌ "1/22/26"

### 简洁性

| 避免             | 推荐 |
| ---------------- | ---- |
| 允许你/您        | 可以 |
| 让我们来看       | 看   |
| 接下来我们将     | 我们 |
| 这个函数的作用是 | 函数 |

### 动词选择

使用精确、具体的动词：

| 模糊动词 | 精确动词               |
| -------- | ---------------------- |
| 处理     | 解析、转换、计算、验证 |
| 获取     | 读取、拉取、提取、请求 |
| 设置     | 配置、赋值、初始化     |

---

## 示例改进

### 改进前（不推荐）

```typescript
/**
 * 这个函数可以帮助我们对用户输入的数据进行处理。
 * 它会返回一个处理后的结果。
 *
 * @param input - 输入的数据
 * @returns 返回处理后的结果
 */
function processData(input: any) {}

/**
 * 这个类是用来管理用户的。
 * 它可以帮助我们进行用户认证。
 */
class UserManager {}
```

### 改进后（推荐）

```typescript
/**
 * Processes user input data.
 *
 * 处理用户输入数据。
 *
 * @param input - User input data to process / 要处理的用户输入数据
 * @returns Processed result / 处理后的结果
 */
function processData(input: Data): Result {}

/**
 * Manages user authentication and session handling.
 *
 * 管理用户认证和会话处理。
 *
 * @example
 * const manager = new UserManager();
 * const session = await manager.login('user@example.com', 'password');
 */
class UserManager {}
```

### 关键改进点

1. **直接描述功能**：开头直接说明函数/类的功能，而非"这个函数是..."
2. **使用动词开头**：函数描述以动词开头（如 Process、Calculate、Validate）
3. **避免冗余**：删除"可以帮助我们"、"这个"等冗余表述
4. **保持简洁**：每行控制在合理长度内

---

## 注释原则

### 不要过度注释

注释是为了增强可读性，而非为注释而注释。过多注释反而会影响代码可读性。

**添加注释前，先问自己**：

1. 不看注释，能否快速理解这段代码的意图？
2. 代码命名是否足够清晰？
3. 注释是否提供了代码本身无法表达的信息？

如果以上问题的答案表明代码已足够清晰，则不需要添加注释。

### 简洁明了

- 避免冗余注释
- 注释应有实际价值
- 提供代码本身无法表达的信息

### 示例要求

- 所有使用示例必须是可以实际运行的代码
- 示例中使用有意义的名称
- 避免使用"foo"、"bar"等无意义占位符