4.5 KiB
4.5 KiB
注释写作风格指南
本指南规范注释的写作风格和语言规范，确保注释专业且一致。
目录
语气标准
视角与时态
- 称呼：以"您"称呼读者
- 语态：使用主动语态
- 时态：使用现在时（例如"函数返回..."而非"函数将返回..."）
语气要求
- 专业：避免口语化和非正式表达
- 友好：保持帮助性的语气，但不冗长
- 直接：开门见山，避免绕圈子
清晰度要求
- 词汇：使用简单词汇，避免过度使用专业术语
- 俚语：避免俚语和口语表达
- 营销用语：避免宣传性和夸张性语言
要求层级
明确区分不同层级的指令：
| 层级 | 用词 | 说明 |
|---|---|---|
| 强制要求 | 必须、严禁 | 必须遵守的规则，违反会导致错误 |
| 强烈建议 | 推荐、建议 | 推荐的最佳实践 |
| 可选建议 | 可以、考虑 | 可根据情况选择的建议 |
避免使用："应当"、"宜"等模糊表述。
措辞选择
| 避免 | 推荐 |
|---|---|
| 请 | （省略） |
| 允许你 | 可以 |
| 允许您 | 您可以 |
| 函数认为 | 函数检查 |
| 数组包含 | 数组有 |
可以使用缩写：不要、它是、它有、它会等。
语言与语法规范
缩写使用
| 避免 | 推荐 |
|---|---|
| e.g. | 例如 |
| i.e. | 即 |
| etc. | 等 |
| vs. | 与...对比 |
| et al. | 等人 |
标点符号
- 序列逗号：在列表中使用逗号分隔（如"a、b、c"）
- 中文引号：使用
""而非"" - 英文引号：使用
""而非 ''
日期格式
使用明确格式，例如：
- ✅ "2026年1月22日"
- ✅ "January 22, 2026"
- ❌ "2026/1/22"
- ❌ "1/22/26"
简洁性
| 避免 | 推荐 |
|---|---|
| 允许你/您 | 可以 |
| 让我们来看 | 看 |
| 接下来我们将 | 我们 |
| 这个函数的作用是 | 函数 |
动词选择
使用精确、具体的动词：
| 模糊动词 | 精确动词 |
|---|---|
| 处理 | 解析、转换、计算、验证 |
| 获取 | 读取、拉取、提取、请求 |
| 设置 | 配置、赋值、初始化 |
示例改进
改进前（不推荐）
/**
* 这个函数可以帮助我们对用户输入的数据进行处理。
* 它会返回一个处理后的结果。
*
* @param input - 输入的数据
* @returns 返回处理后的结果
*/
function processData(input: any) {}
/**
* 这个类是用来管理用户的。
* 它可以帮助我们进行用户认证。
*/
class UserManager {}
改进后（推荐）
/**
* 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 {}
关键改进点
- 直接描述功能：开头直接说明函数/类的功能，而非"这个函数是..."
- 使用动词开头：函数描述以动词开头（如 Process、Calculate、Validate）
- 避免冗余：删除"可以帮助我们"、"这个"等冗余表述
- 保持简洁：每行控制在合理长度内
注释原则
不要过度注释
注释是为了增强可读性，而非为注释而注释。过多注释反而会影响代码可读性。
添加注释前，先问自己：
- 不看注释，能否快速理解这段代码的意图？
- 代码命名是否足够清晰？
- 注释是否提供了代码本身无法表达的信息？
如果以上问题的答案表明代码已足够清晰，则不需要添加注释。
简洁明了
- 避免冗余注释
- 注释应有实际价值
- 提供代码本身无法表达的信息
示例要求
- 所有使用示例必须是可以实际运行的代码
- 示例中使用有意义的名称
- 避免使用"foo"、"bar"等无意义占位符