doc-comment-writer

文档注释编写指南

编写经久耐用的文档注释，帮助未来的维护者了解用途、契约、约束和不显而易见的决策，而不必从实现中重新推断。仅仅复述名称、类型或直观的控制流并不算说明，应予以省略。

工作流

1. 明确范围和本地约定。

   • 遵循用户说明的范围。判断该语言通常使用的文档注释形式，以及文件现有的风格和注释密度。
   • 仅在需要了解公开行为或重要不变量时，检查附近的类型、测试、调用方或同级文件。
   • 明确范围内的文件和符号，以及适用的注释语法和风格后，继续操作。

2. 明确决定保留、修改或跳过。

   • 如果文件的职责、边界或用法模式无法从其名称和导出内容中明显看出，请考虑添加文件级注释。
   • 如果未来的读者需要检查内部逻辑才能回答“这是做什么的？”或“哪些条件必须保持不变？”，请添加注释。
   • 仅在删除现有注释会导致读者失去相关信息时才保留。修改过时或不清楚的注释，并删除仅仅叙述声明或实现的注释。
   • 如果符号的名称、签名、类型和上下文已足以回答相关问题，则无需为其编写文档。如果文件不需要新注释，应直接说明，而不是强行修改。
   • 在继续操作前，明确决定范围内每个导出或公开符号、每条现有文档注释，以及任何相关文件头注释应保留、添加、修改、删除还是跳过。

3. 编写并验证经久耐用的注释。

   • 对每条新增或修改的注释应用《注释标准》中的所有规则。
   • 仅在局部不变量或微妙分支需要超出文档注释所能表达的说明时，才使用行内注释。
   • 运行最有针对性的相关格式化工具、解析器、lint、文档或示例检查。如果没有可用工具，请检查已更改的注释语法，并报告这一限制。
   • 所有已更改的注释均符合标准、使用有效的本地语法，且相关验证已通过或已报告限制后，方可完成。

注释标准

• 在重要的情况下，说明保证、副作用、失败模式、生命周期预期、不变量、边界、误用风险或经久耐用的权衡。
• 文件级注释应简短且侧重结构。优先使用一条有力的文档注释，而不是几条作用薄弱的注释。
• 对于易变更的事实，例如数值阈值、超时、限制、默认值、常量值、成员列表、文件名和路径，应以代码、类型和配置为准。描述语义规则，不要在说明文字中照抄字面值或列表；只有读者确实需要时才提及所属符号。如果无法解释的字面值需要命名，应报告代码可读性问题，而不是试图用文档注释掩盖。
• 外部引用应视为例外。不要引用计划、进度文件、交接记录、临时决策日志或问题与拉取请求讨论串等临时或维护薄弱的材料。应在注释中写明经久耐用的理由；只有当某份文档是权威且持续维护的规范或契约，并且位置稳定时，才引用它。
• 避免使用随时间变化的措辞，以及常规改动后就会过时的分步实现细节。
• 对代码推断出的行为应谨慎表述；不要虚构实现无法支持的意图或保证。
• 如果无法根据仓库证据确定重要理由，应提出有针对性的维护者问题，而不是撰写推测性注释。
• 删除泛泛的填充文字和复述内容。每条注释都应在不查看所记录符号的实现时仍然有用。

目标指南

适合添加注释的内容包括文件或模块边界、公开保证与失败行为、类型语义与生命周期，以及用于落实复杂不变量、协议或规范化规则的内部辅助函数。

跳过仅仅复述文件名的文件头、简单的访问器和包装器、对参数或类型的描述、直观的控制流，以及大段照搬实现细节的内容。

回复要求

• 除非用户同时要求重构，否则将差异限定在文档修改范围内。
• 编辑后，简要报告新增、修订或删除的注释；值得注意的跳过决定；验证情况；以及对于仍不够清晰、无法有把握地编写文档的代码提出的具体问题。