documentation

文档

Microsoft 合约优先约定。文档说明合约——某项内容的作用和原因——而不是其内部实现方式。

为什么规则旨在精简

代码会变更，旁边的注释通常不会。时间久了，文档就会变得不实，但读者仍会相信它——过时的注释比没有注释更糟，因为它会主动误导读者。因此，要养成两种习惯，下面的每条规则都是其中一种习惯的具体应用：

精简表面内容。 文字越少，过时的内容就越少。注释是最后手段，而不是第一步：写注释前，先想想更准确的名称、更小的函数或命名类型是否能表达其含义。文字说明只用于补充代码确实无法表达的内容。

**每条事实只放在一个地方，**紧挨着负责维护它的代码，这样恰好只需更新一处。当签名、类型或测试已经说明某件事时，文字说明就不应再重复。

最简原则

签名已经包含名称、参数名称和类型、返回类型及修饰符（readonly、?、async）。文档只补充读者无法从签名推断出的内容：意图、单位、范围、默认值、边界值含义、错误情况和不变量。

每个公开成员仍需提供简短摘要，以便生成的文档和 IDE 工具提示有内容——用一个简短句子说明意图，绝不改写签名。

对于 @param 和 @returns，如果标签只会重复签名内容，就完全删掉该标签。 只有在回答以下问题时，标签才有必要：单位是什么？范围或钳制值是多少？省略时的默认值是什么？边界值代表什么（0 表示禁用，-1 表示不限制，空值 = 全部）？null 与抛出异常分别表示什么？

@throws 的默认规则恰好相反——只要代码可能抛出异常，就记录下来，因为签名无法体现可能抛出的异常。

文档块的形式

文档块会显示在 IDE 工具提示、悬停卡片和代码审查差异中——这些界面会展示开头，然后截断其余内容。因此，篇幅按渲染后的行数计算，而不是按句子数计算：

• 摘要——恰好一行。 用一个句子说明意图，单独放在文档块顶部。不能占两行，也不能写两个句子。
• 详情——最多三行，放在一个空行之后，并且只有在摘要确实无法涵盖合约时才添加。只写主要内容：操作的作用及其约束条件，而不是分支方式。
• 行内 // 或 # 注释——最多三行，最好一行。

内容超出限制时，不能靠重新换行来解决；这意味着内容放错了位置。分支行为、边界情况和约束背后的理由应放到 @remarks（Python 中为 Note: / Notes）中，这样文档块的开头才能保持易读。

格式化后再衡量，而非格式化前。 写好文档块后，使用项目的格式化工具，按照配置的宽度重新排版（检测顺序见 Conventions），再统计生成的行数。若摘要被折成两行，就超出了限制：删减文字，直到它能放在一行内——不要把它拆成第二个句子，因为那样的句子只是伪装成摘要的详情。格式化工具或 max-len 规则将行内注释延展到三行以上时，也要进行同样的检查。

文档读起来是什么感觉

你在这里写的每句话——摘要、保留下来的 @param 说明、@throws 条件、端点描述——都会在调试过程中被阅读，而读者可能不会说你的母语。深入掌握 simple-english 技能（/cortex:simple-english practical），并在写作时遵循其中的规则。要在写第一个文档块之前就用上它，而不是留到最后润色：重写已经定稿的文字，比一开始就写对成本更高。

具体来说，它会怎样改变文档块：

• 同一文件中，每个概念只用一个词。 @param 写“validate”，摘要却写“check”，读者会以为这是两种不同操作，然后开始寻找差异。
• 描述性句子不超过 25 个词，祈使句不超过 20 个词。 摘要超过这个长度，就承载了不止一个事实，应放到 @remarks 中。在常见的行宽下，单行限制通常会先起作用，因此要把词数当作上限，并以渲染后的行作为检验标准。
• 用 can、will、must，绝不用 should。 如果契约说调用方“should”传入已排序的数组，读者就会猜这条规则是否有约束力。要么说 must，要么说明不遵守时会发生什么。
• 先说条件，再说结果。 “如果 retries 为 0，调用会立即失败”优于反过来的顺序，因为读者在理解结果之前就能知道这句话是否适用于自己。
• 没有具体依据，就别用形容词。 “高效缓存”毫无意义。给出具体界限，或者删掉这个词。

标识符、代码示例和引用的错误字符串必须保持原样——规范将它们视为技术名称，读者复制所谓“修正”后的内容，只会遇到新的错误。

约定

• 代码符号的摘要使用第三人称——“计算……”“查找……”“初始化一个新的……”——符合 Microsoft API 参考文档的惯例。两个例外使用祈使句：描述操作步骤的行内 // 注释，以及 API 操作的 summary 字段（OpenAPI、@ApiOperation、extend_schema），其中“Create a new user”是惯用形式。
• 接口文档说明抽象：用途、抛出的错误、返回语义和不变量。实现细节（缓存、查询、算法）应放在实现中——阅读接口的使用者不应了解到重构后可能失效的信息。
• 数据结构说明是什么，而不是为什么。 DTO、记录、结构体，或用于描述它们的 interface／type，应说明每个成员是什么——含义、单位、格式、允许值，以及类型本身无法表达的约束。不要为字段存在的原因辩解。函数的契约确实包含操作背后的原因；数据字段则是在使用时读取，此时设计理由（“保留该字段以便计费核对……”）会逐渐过时，应该放在产生或使用该字段的行为说明中。例外情况——维护者绝不能破坏的非显而易见约束——应少量写入 @remarks，而不是作为默认写法。
• 不要在实现中重复接口文档。 继承文档（使用 @inheritDoc 或该语言的等效机制），只补充实现特有的说明。
• 只使用多行文档块。 每个 /** 后都要换行再写正文；不允许使用单行 /** … */。
• 除非明确要求，否则不要添加发布标签（@public、@beta、@alpha、@internal）。
• 只提供测试套件会运行的示例。 未执行的示例会逐渐过时，成为又一条不实的注释。运行时会执行的 Python doctest 符合要求（pytest --doctest-modules）；工具不会执行 TSDoc @example 代码块，因此应省略它们，让测试说明行为。
• 按照项目配置的行宽换行。 按以下顺序检查：.editorconfig 中的 max_line_length → 格式化工具配置（printWidth、line-length）→ 代码检查工具配置（max-len、max-line-length）。只有在这些配置都未定义行宽时，才回退到 80 个字符。

看到就删除的注释

审查时，删除这些注释和补齐文档缺漏同样重要——它们都可能导致信息与事实脱节：

• 已注释掉的代码——版本控制已经记录了它，保留它只会让读者疑惑它是否仍有用。
• 日志或变更记录注释（“2024-03 added retry logic”）——git log 能准确记录这些信息。
• 署名行（“added by …”）——git blame 可以解答，无需让署名信息逐渐过时。
• 横幅、位置标记、右花括号标签（// ===== helpers =====、} // end if）——代码本身应体现结构。
• 任何复述名称、类型或签名，或陈述显而易见内容的注释（/** Default constructor */）。

处理文档任务

开始前，先询问项目使用哪种格式（或从现有文件中识别），并识别其框架——不同框架的 API 文档策略各不相同，套用错误的策略会产出无人使用的规范。

汇报质量，而非数量。目标不是让每个成员都有文档块，尤其是其中一半都在复述签名时。应汇报具体改进：删除了冗余内容、修正了过时文档、补充了意图摘要和 @throws。覆盖率百分比只是最低限度的参考——它能找出空白成员，却无法区分有价值的文档块和空洞的文档块。

参考资料

参考资料	何时加载
references/python-docstrings.md	Python——Google、NumPy 或 Sphinx 风格
references/typescript-jsdoc.md	TypeScript/JavaScript——TSDoc 标签、@inheritDoc、格式
references/api-docs.md	REST API 文档——NestJS、Express、FastAPI、Django
references/coverage-reports.md	审查文档；生成文档健康报告