comment-and-documentation-quality

注释、文档和提交信息质量标准

核心理念

代码注释、文档和提交信息必须简洁说明用法、不明显的限制和关键的 原因，而不是讲解内部机制、记录逆向工程过程或写成对话式故事。

好的文字能阐明意图和不明显的不变量。如果代码、参数名称或类型签名已经能说明某件事，注释就是有害的噪音。在提交信息中，简洁说明技术理由，不要写叙事式日志。

---

注释与文档的 7 种反模式

1. 标点问题：长破折号（—）、短破折号（–）和双连字符（--）

• **规则：**注释、文档字符串、技术性文字或提交信息中，绝不要用长破折号（—）、短破折号（–）或双连字符（--）表示对话中的停顿。
• **改进方式：**使用标准连字符（-）、冒号（:）、括号，或拆分成独立句子。
• ❌ // Set timeout — defaults to 5000ms
• ❌ * wrote -- and it really does drop writes -- so we read back
• ✅ // Set timeout (defaults to 5000ms)
• ✅ * Read back row after write to verify updates.

2. 错置的内部机制与后端细节（README / 快速入门内容臃肿）

• **规则：**绝不要在面向使用者的示例或 README 中解释深层后端实现、限流内部机制、隐藏的查询成本或运维权衡。
• **改进方式：**从快速入门中彻底删除，或精简成一条清晰的参数说明。
• ❌

  // Memrise rate-limits the account and silently drops writes when it bites, so
  // each call costs a read-back. Trim the requests when that matters: numeric
  // keys need no name lookup, poolId saves the one that finds the thing's pool,
  // and verify: false drops the read-back (and with it any proof it worked).
  

• ✅

  Pass `verify: false` to skip write verification on high-volume updates.
  

3. 布尔选项的冗长说明与夸张评论

• **规则：**绝不要用多句话长篇解释布尔选项的 true 和 false 状态、默认值存在的原因，或戏剧化描述外部 API 的行为（如“信任一个沉默的 API”）。
• **改进方式：**用一句话说明该标志控制什么，并配上标准的 @default 标记。
• ❌

  /**
   * Read the row back and confirm the new values are there. On by default,
   * because the endpoint reports the same thing whether or not it wrote.
   * Turning it off saves one request per call and trusts a silent API.
   */
  verify?: boolean;
  

• ✅

  /**
   * Whether to read back and verify updated row data.
   * @default true
   */
  verify?: boolean;
  

4. 信封与类型转换的闲谈

• **规则：**绝不要在文档字符串中为单行 JSON 解包、属性剥离或结构转换作解释（例如说明为何剥除了信封键）。
• **改进方式：**说明函数返回什么。TypeScript 返回类型定义了架构。
• ❌

  /**
   * The signed-in account, as `/v1.25/me/` reports it.
   *
   * The wrapping `profile` key is dropped, since the response carries
   * nothing else.
   */
  async getMe(): Promise<Profile>
  

• ✅

  /**
   * Fetches the current signed-in user profile.
   */
  async getMe(): Promise<Profile>
  

5. 来源传说与逆向工程日志

• **规则：**绝不要留下说明你如何逆向得出某个类型、发现某个端点架构，或解释为何存在开放索引签名的备注。
• **改进方式：**记录类型表示什么，而不是如何发现它。
• ❌

  /**
   * The signed-in account. Fields below were observed on a live response; the
   * index signature covers the rest, since this payload carries whichever
   * subscription and entitlement flags the web client happens to need.
   */
  export interface Profile { ... }
  

• ✅

  /**
   * Signed-in user profile.
   */
  export interface Profile { ... }
  

6. 幽灵注释与墓碑注释（“曾经删除了什么”）

• **规则：**绝不要留下说明代码过去做什么、经过哪些重构或现在哪些内容不再需要的注释。
• **改进方式：**彻底删除。版本控制历史会记录过去的状态。
• ❌ // We no longer call legacyValidate() here since v2 handles it in middleware
• ❌ // Removed old API endpoint because it's deprecated
• ✅ （不写注释）

7. 同义反复的注释与逐步叙述

• **规则：**绝不要用英文复述一目了然的代码，也不要讲述基本的操作步骤。
• **改进方式：**彻底删除。
• ❌ // set loading state to false 写在 setLoading(false) 之前
• ❌ // Step 1: Initialize list / // Step 2: Filter items
• ✅ （不写注释）

---

提交信息

审核提交信息时，请阅读 commit-messages.md，了解相关标准、反模式和发现记录模板。编写或修改提交时，在可用的情况下使用 git-commit-quality，并遵循仓库的提交规范。

合理的注释（应保留的内容）

始终保留：

1. **不明显的领域逻辑：**业务规则、边缘情况计算或时序不变量。
2. **上游缺陷的变通方案：**平台或浏览器特性，尤其是附有问题链接的情况。
3. **公共 API 契约：**标准的 @param、@returns 和 @throws 文档。
4. **可执行的注释标记：**明确的 TODO:、FIXME: 或安全提示。

---

标准审计结果模板

审计代码、文档字符串或提交消息时，请使用以下结构格式化审计结果：

代码和文档：

### `path/to/file.ts:L42` — `<context/symbol name>`
- **Original:** `<exact original comment or docstring text>`
- **Anti-Pattern:** `<Anti-Pattern Name(s)>`
- **Issue:** `<1-sentence concise explanation of what makes it noise/bloat>`
- **Replacement:** `<Clean drop-in replacement, or *(Delete entirely)*>`