document-code

文档化代码

在不改变行为、结构或公开契约的前提下，提升代码的可理解性。只在确有价值时添加文档：充分说明意图、不变量和不明显的权衡取舍，但不要复述显而易见的代码。

范围

• 如果用户提供了选定或标记的代码，则使用这些代码。
• 如果用户指定了目标文件、目录、符号或描述，则使用指定目标。
• 如果用户要求进行一般性文档整理，但未指定目标，则先检查已暂存的源代码更改；若没有已暂存的更改，则检查未暂存的源代码更改。
• 将编辑范围限制在目标或差异中所含语言的源代码文件。根据扩展名、项目布局、导入项和构建配置判断哪些是源文件；扩展名列表并非穷尽。
• 除非用户明确要求编辑，否则排除文档、JSON、YAML、锁定文件、生成文件、图片及其他非代码文件。
• 过滤后若没有剩余源代码文件，则说明没有需要文档化的内容，并且不做任何更改。

硬性约束

• 不得编辑可执行行为。
• 不得重命名符号、调整逻辑顺序、简化代码、提取辅助函数、重构文件或更改格式。
• 不得更改 API、类型、序列化数据、用户可见文本、错误、快照、分析事件、无障碍语义、时序、顺序或持久化行为。
• 只能添加或改进以下形式的文档：
  • 行内注释
  • 符合语言习惯的 API 文档，例如 docstring、doc 注释、JSDoc、rustdoc、Go doc 注释、XML 文档或项目中的等效惯例
  • 符合第 5 步条件的专题文档文件
• 如果代码不清晰是因为需要简化、重命名或重构，则不要在此工作流中修复；应说明这一限制。

工作流

1. 确定目标。

   • 优先使用用户明确选定的内容或标记的文件，而非范围更广的差异。
   • 避免修改无关文件，即使附近代码也可能受益于文档说明。

2. 阅读足够的上下文。

   • 检查调用方、导出的 API、测试、类型、附近的注释、现有文档和本地惯例；如果提交历史和 PR 历史有助于解释意图，也应查看——它们往往是记录原因的唯一地方。
   • 在编写文档前理解行为：输入、输出、副作用、错误路径、生命周期顺序、重试、幂等性、并发、持久化和业务规则。
   • 只有在能够说明行为以及目标中每个不明显部分背后的原因后，才停止阅读。
   • 如果经过合理阅读后意图仍不明确，应如实说明，而不是编造理由：如今看来合理的代码，编写时的原因可能已不再适用，事后补上的理由也可能变成错误文档。
   • 优先采用项目中已有的术语，而非创造新词。

3. 只记录有助于理解的内容。

   • 记录不明显的不变量、假设、前置条件和所有权规则，以及背后的权衡、被否决的替代方案，以及兼容性或迁移限制。
   • 区分有意为之的意外行为和意外发生的行为：由外部依赖、平台或协议所强制，或出于某种原因（限制、权衡）而选择的行为，值得添加注释；没有合理依据、令人困惑的结构则应作为重构目标——将其归入 Needs refactor, but not changed，而不是用注释掩盖问题。
   • 说明并发、顺序、清理、重试、退避和幂等性方面的预期，以及容易被误解的回退、故障模式或边界行为。
   • 记录仅凭语法不易看出的业务或领域规则。
   • 如果读者有理由想知道私有辅助函数为何存在，就说明其用途。
   • 当参数含义、返回语义、副作用、错误、不变量、领域规则或生命周期职责无法从签名中明显看出时，为公共 API、导出 API 和复杂的私有辅助函数编写符合语言惯例的 API 文档。
   • 简单的私有函数只要名称和签名清晰即可；为明显的代码强制添加文档字符串只会造成噪声，且文档容易过时。

4. 保持清晰的代码原样。

   • 只有在有经验的读者会停下来问“为什么”时才添加注释；如果你说不出这个问题，就不要添加注释。
   • 注释应聚焦于意图和稳定行为，确保实现细节改变后依然准确。
   • 如果每种边界情况都需要单独注释，应在总结中建议编写测试，而不是逐条列出注释。同样，对于“不得更改”的不变量，应记录它，并在总结中建议最易执行的检查方式——类型、测试或 lint；文字说明无法强制执行。

5. 将文档写在合适的位置。

   • 默认使用局部注释。如果理由适用于单个分支、辅助函数或调用点，就在其旁边添加注释。
   • 在负责不变量的边界处说明一次，而不是在每个使用方重复说明：读者只需了解一次，也能避免副本内容不一致。
   • 只有同时满足以下所有条件时才选择文档文件：理解代码需要这些理由，且涉及两个或更多文件或模块；将其放在任一单独位置旁边都会丢失上下文；内联说明会在多个位置重复。犹豫不决时，保留为局部说明。
   • 保持唯一事实来源：在文档文件中写出完整理由，然后只在附近读者需要指引和即时理由的地方，留下简短的局部注释指向该文档。
   • 对于专门的文档文件，如果跨模块结构、生命周期或顺序用图示比文字更容易理解，就使用图示（时序图、状态图、流程图）。如仓库已有图示规范，则遵循；否则在 Markdown 文件中默认使用 mermaid。不要将一句话就能说明的内容画成图，并确保图示描述的是稳定行为，而非会变化的实现细节。
   • 尽可能将新文档放在相关现有文档旁边，并严格限定其范围。

6. 遵循局部风格。

   • 遵循仓库的注释风格、特定语言的文档规范、大小写、标点和术语。
   • 注释应靠近其说明的代码。
   • 除非公共 API 或多步骤不变量需要结构化说明，否则优先使用简洁注释，而非块注释。
   • 保留有用的现有注释；仅在目标范围内审查已修改区域中的现有注释和文档字符串，并修正任何与实现、行为、约束或公共契约不符的过时或误导性内容。

7. 验证结果。

   • 重新检查差异，确认只修改了注释、文档字符串或明确需要更新的文档。
   • 确认未改动可执行代码、仅涉及格式的结构、生成文件和无关文件。
   • 检查每条新增注释是否说明了意图、理由、约束或非显而易见的行为。
   • 如果注释或文档字符串可能影响工具运行，请在可行时运行范围最小的相关验证，例如 lint 或文档检查。
   • 如果检查不可用，或对仅修改注释的变更来说没有必要，请说明原因。

输出

根据变更规模提供简洁的摘要。对于小任务，使用一小段文字或 2-4 条具体要点，说明记录了哪些内容，以及是否运行了验证。

对于较大规模的文档整理，只包含能提供有用信息的部分：

• 已记录：说明读者现在可以从代码中了解到哪些此前未说明的内容——不变量、权衡或约束，以及它所在的位置（最近的符号或文档文件），不要罗列新增注释的文件。
• 需要重构，但未改动：列出实际需要通过简化、命名或调整结构来澄清的部分。
• 验证：列出运行的命令及结果，或说明未运行的原因。
• 范围：用一行列出已检查的文件。

不要声称行为发生了变化、修复了 Bug 或简化了代码。交付内容应帮助读者更好地理解，同时保持行为不变。