187 lines
4.5 KiB
Markdown
187 lines
4.5 KiB
Markdown
# 注释写作风格指南
|
||
|
||
本指南规范注释的写作风格和语言规范，确保注释专业且一致。
|
||
|
||
## 目录
|
||
|
||
- [语气标准](#语气标准)
|
||
- [语言与语法规范](#语言与语法规范)
|
||
- [示例改进](#示例改进)
|
||
|
||
---
|
||
|
||
## 语气标准
|
||
|
||
### 视角与时态
|
||
|
||
- **称呼**：以"您"称呼读者
|
||
- **语态**：使用主动语态
|
||
- **时态**：使用现在时（例如"函数返回..."而非"函数将返回..."）
|
||
|
||
### 语气要求
|
||
|
||
- **专业**：避免口语化和非正式表达
|
||
- **友好**：保持帮助性的语气，但不冗长
|
||
- **直接**：开门见山，避免绕圈子
|
||
|
||
### 清晰度要求
|
||
|
||
- **词汇**：使用简单词汇，避免过度使用专业术语
|
||
- **俚语**：避免俚语和口语表达
|
||
- **营销用语**：避免宣传性和夸张性语言
|
||
|
||
### 要求层级
|
||
|
||
明确区分不同层级的指令：
|
||
|
||
| 层级 | 用词 | 说明 |
|
||
| -------- | ------------------ | ------------------------------ |
|
||
| 强制要求 | **必须**、**严禁** | 必须遵守的规则，违反会导致错误 |
|
||
| 强烈建议 | **推荐**、**建议** | 推荐的最佳实践 |
|
||
| 可选建议 | **可以**、**考虑** | 可根据情况选择的建议 |
|
||
|
||
**避免使用**："应当"、"宜"等模糊表述。
|
||
|
||
### 措辞选择
|
||
|
||
| 避免 | 推荐 |
|
||
| -------- | -------- |
|
||
| 请 | （省略） |
|
||
| 允许你 | 可以 |
|
||
| 允许您 | 您可以 |
|
||
| 函数认为 | 函数检查 |
|
||
| 数组包含 | 数组有 |
|
||
|
||
**可以使用缩写**：不要、它是、它有、它会等。
|
||
|
||
---
|
||
|
||
## 语言与语法规范
|
||
|
||
### 缩写使用
|
||
|
||
| 避免 | 推荐 |
|
||
| ------ | --------- |
|
||
| 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"等无意义占位符
|