• 文档

导读

本文基于 Google styleguide 仓库 docguide/best_practices.md 编写，系统讲解 Google 文档工程的核心方法论：从"最小可行文档（Minimum viable documentation）"、"随代码更新文档（Update docs with code）"、"删除死文档（Delete dead documentation）"，到"宁好勿完美（Prefer the good over the perfect）"与"文档是代码的故事（Documentation is the story of your code）"。读完本文，你将掌握一套可复制的文档健康维护流程，并理解内联注释、方法/类注释、README 三级文档体系各自承担的角色与写作标准——这套规范不仅适用于本仓库（其 docguide 目录本身就是最佳实践的活样本），也适用于任何需要长期维护的工程仓库。

一、最小可行文档：文档的"盆景"哲学

"A small set of fresh and accurate docs are better than a sprawling, loose assembly of 'documentation' in various states of disrepair."

1.1 核心主张

一份少量、新鲜、准确的文档，胜过一堆零散、破旧、处于各种失修状态的"文档库"。这是整个 best_practices 文档的基石思想：文档的数量与篇幅从来不是目标，可读、可用、可信才是。

原文档用了一个生动的比喻：文档的最佳状态是"活的但经常修剪"，就像一盆盆景（bonsai tree）。盆景之美不在于枝条繁多，而在于持续照料、不断修剪后的形态。与之对应，文档应该：

• 持续地"按摩"和打磨每一份文档，使其适配团队不断变化的需求；
• 像维护测试用例那样认真对待文档的更新维护，而不是写完即弃；
• 鼓励工程师以"拥有者"心态（take ownership）对待文档，保持其新鲜度。

1.2 两条可执行建议

原文档给出两个具体动作：

1. 识别你真正需要什么：发布文档（release docs）、API 文档、测试指南（testing guidelines）……先明确业务真正需要的文档清单，而不是什么都写。
2. 频繁小批量清理（Delete cruft frequently and in small batches）：清理"赘肉"文档要像日常扫除一样高频、小步进行，避免攒成大扫除任务而难以执行。

1.3 仓库佐证：docguide 目录本身就是"最小可行"的样本

本仓库的 docguide/ 目录正是这一思想的直接体现——它只包含 5 份小而精的文件：

• README.md：目录入口，4 行导航 + See also；
• style.md：Markdown 格式规范；
• best_practices.md：本文主体；
• READMEs.md：README 编写指南；
• philosophy.md：文档哲学。

每份文档职责单一、篇幅克制，没有冗余的"官方套话"。配套的 philosophy.md 进一步阐述了这一取向，其中"Minimum viable documentation"一节与本文直接呼应：

"Brief and utilitarian is better than long and exhaustive. The vast majority of users need only a small fraction of the author's total knowledge, but they need it quickly and often."

（简短实用优于冗长详尽。绝大多数用户只需要作者全部知识的一小部分，但他们需要快速、频繁地获取它。）

同时 philosophy.md 提出文档应当像测试一样被对待："Docs thrive when they're treated like tests: a necessary chore one learns to savor because it rewards over time."——这正是 best_practices 中"以维护测试的热情维护文档"的哲学根源。此外，"Radical simplicity（激进简洁）"一节强调：新功能不应干扰最简单的用例，规模与互操作来自简洁——这条原则同样适用于文档结构设计。

二、随代码更新文档：同一 CL 内完成修改

"Change your documentation in the same CL as the code change. This keeps your docs fresh, and is also a good place to explain to your reviewer what you're doing."

2.1 规则本身

文档必须和代码变更放在同一次 CL（Change List，代码评审中的变更集）里提交。这样做有三个直接收益：

1. 文档保持新鲜：代码与文档永远同步，不会出现"代码已改、文档过期"的漂移；
2. 评审上下文完整：在同一个 CL 中，文档本身就是向 reviewer 解释"你在做什么、为什么这样做"的最佳载体；
3. 强制更新机制：一个好的 reviewer 至少应当坚持 docstring、头文件、README.md 及其他文档随 CL 一起更新。

换言之，文档更新不是代码提交之后的"补作业"，而是提交的一部分。这条规则将文档维护从"事后自觉"升级为"流程内置"。

2.2 仓库佐证：docguide 与代码的同步维护

本仓库可以观察到大量"文档与代码同步"的实例：

• docguide 内部互链：best_practices.md 中"README.md"一节直接链接到 READMEs.md；philosophy.md 的"Minimum viable documentation"一节又链接回 best_practices.md。文档集内部互相指引、随内容演进同步更新，而不是各自孤立漂移。
• cpplint 工具与其文档： cpplint/README 描述 cpplint.py 的用途与用法（"The linting tool takes a list of files as input. For full usage instructions, please see the output of:./cpplint.py --help"），而 cpplint/cpplint.py 的实现细节变化、新增的检查规则，都需要在 README 与 cpplint_unittest.py 测试用例中同步体现。从源码结构看，README 中"heavily relies on regular expressions"的描述与 cpplint.py 基于正则的实现方式（cpplint 是"automated checker"）一致，也印证了文档描述跟随实现更新的必要性。
• 版本文件：docguide/VERSION（内容为1.0）这类元信息文件同样属于需要随内容变更而更新的文档范畴。

三、删除死文档：让坏文档止步于源头

3.1 为什么死文档有害

原文档对"死文档（Dead docs）"的批判非常直接：

• 误导（misinform）：过期信息比没有信息更危险；
• 拖慢（slow down）：读者需要花费时间甄别真伪；
• 打击士气（incite despair）：让工程师沮丧、让团队领导懒惰；
• 树立坏先例（set a precedent）：为代码库遗留混乱开了口子。

原文档用一个巧妙的类比收尾："如果你的家是干净的，大多数客人不需要被要求也会保持干净。"（If your home is clean, most guests will be clean without being asked.）——干净的文档环境会自然抑制新垃圾的堆积。

3.2 大规模清理的五步法

原文档清醒地指出："像任何大扫除项目一样，很容易被淹没（it's easy to be overwhelmed）。" 因此给出了循序渐进的清理流程：

1. 慢慢来（Take it slow）：文档健康是渐进积累的结果（doc health is a gradual accumulation）；
2. 先删确定错误的，忽略含糊不清的：对拿不准的内容不要纠结，先处理 100% 确认错误的部分；
3. 让整个团队参与：投入时间快速扫描每份文档，做出简单决策——保留还是删除（Keep or delete?）；
4. 默认删除或迁移时保留：迁移（migrating）中的文档若犹豫不决，默认删除或留在原地——掉队者（stragglers）随时可以找回（版本控制保证了这一点）；
5. 迭代（Iterate）：重复以上循环，逐步逼近健康状态。

这一流程与本文第一节"频繁小批量清理"互相呼应：日常小修剪 + 阶段性的全员大扫除，双管齐下。

四、宁好勿完美：文档评审的 Good Over Perfect 法则

"Your documentation should be as good as possible within a reasonable time frame."

4.1 评审标准的差异

原文档明确区分了文档评审与代码评审的标准：

• 文档评审的严格程度不同于代码评审；
• Reviewer 可以也应该要求改进，但作者应当始终能够援引"Good Over Perfect Rule"（宁好勿完美法则）；
• 与其反复评审直到"完美"，不如让作者快速提交能改进文档的变更。

根本原因在于：文档永远不会完美（Docs are never perfect），它只会在团队逐步搞清楚"我们到底需要写些什么"的过程中渐进变好。追求完美只会阻塞迭代，而快速提交 + 持续改进才是正循环。

4.2 仓库佐证：philosophy 的哲学呼应

philosophy.md 的"Better is better than perfect"一节给出了两条支撑原则：

"Incremental improvement is better than prolonged debate. Patience and tolerance of imperfection allow projects to evolve organically."

（渐进改进优于无休止的争论。对不完美的耐心与容忍，让项目有机进化。）

以及 "Don't lick the cookie, pass the plate（别舔了饼干，把盘子传下去）"——面对海量潜在项目，只挑选自己真正能承担的，把承担不了的释放出去。这条原则同样适用于文档：不要因为追求某一份文档的完美而阻塞整个文档体系的推进。

五、文档是代码的故事：从注释到 README 的三级谱系

"Writing excellent code doesn't end when your code compiles or even if your test coverage reaches 100%."

原文档指出：写出计算机能理解的代码很容易，写出人类和计算机都能理解的代码则难得多。作为有 Code Health 意识的工程师，使命是"write for humans first, computers second（先为人类而写，其次才是计算机）"，文档正是这一能力的重要组成。

原文档给出了一条工程文档的"谱系"，从最简到最详依次为：

1. 内联注释（Inline comments）
2. 方法注释与类注释（Method and class comments）
3. README.md

5.1 内联注释：解释"为什么"

内联注释的首要目的是提供代码本身无法承载的信息——尤其是"为什么这段代码在这里"。它不重复代码已经明示的"做什么"，而是补充动机、约束和背景。

5.2 方法 API 文档：代码行为的契约

方法 API 文档（header / Javadoc / docstring）回答"方法做什么、怎么用"，它是代码行为方式的契约（the contract of how your code must behave），目标读者是未来将使用和修改这段代码的程序员。原文档给出了一个实用原则：

这里记录的任何行为，通常都应当有对应的测试来验证。（any behavior documented here should have a test verifying it）

这正好呼应了本文开头"像维护测试一样维护文档"的取向——文档里承诺的行为，测试来兜底。方法 API 文档应覆盖：

• 方法接收什么参数（arguments）；
• 返回什么（returns）；
• 有哪些"坑"或限制（gotchas / restrictions）；
• 可能抛出什么异常或返回什么错误（exceptions / errors）。

它通常不解释"为什么代码以这种方式行为"——那是内联注释的职责。写方法文档时要"务实"：原文档用了一句极简的话示范——"这是一把锤子，你用它来钉钉子。"（This is a hammer. You use it to pound nails.）

5.3 类 / 模块 API 文档：概述 + 简短示例

类 / 模块 API 文档（类或整个文件的 header / Javadoc / docstring）提供：

• 该类 / 文件做什么的简要概述；
• 几个如何使用该类 / 文件的简短示例。

示例尤其重要当存在多种不同的使用方式（有高级用法、有简单用法）时。此时有一条硬性规则：始终先列出最简单的用例（Always list the simplest use case first）。

5.4 README.md：目录的着陆页

README 的作用是为新人指路，把读者引向更详细的说明和用户指南。一份好的 README 至少回答三个问题：

• 这个目录打算存放什么（What is this directory intended to hold?）；
• 开发者应该先看哪些文件？其中哪些是 API？（Which files should the developer look at first? Are some files an API?）；
• 谁在维护这个目录，我可以在哪里了解更多？（Who maintains this directory and where I can learn more?）

原文档在此处链接了完整的 README.md 编写指南（READMEs.md），该文档从 Overview、Guidelines、Filename、Contents、Example 五个角度给出了可操作规范。

六、落地延伸：README.md 指南与仓库实例

6.1 READMEs.md 核心规范

READMEs.md 是对 best_practices 中 README 论述的完整展开，可作为写作 README 时的 checklist：

• 定位：README.md 是 Markdown 文件，用来描述一个目录；在 GitHub / Gitiles 中浏览目录时会自动渲染，是读者（尤其首次使用者）最先遇到的着陆页（landing page）。
• 推荐范围：代码的顶层目录、尤其是为其他团队提供接口的包目录，应当有最新的 README.md。
• 文件名：统一使用README.md——在 Gitiles 中，名为README（无扩展名）的文件不会显示在目录视图里。
• 最低内容要求（每份包级 README 至少包含或指向以下四项）：
  1. What：这个包 / 库是什么、用来做什么；
  2. Who：联系谁（维护者）；
  3. Status：状态——是否已弃用（deprecated）、是否面向一般发布等；
  4. More info：更详细文档的入口，例如 overview.md、API 文档。

6.2 仓库内的活样本：根 README 与 cpplint README

本仓库恰好提供了两个可直接对照的实例：

• 根目录 README.md：开头一句话说明项目是什么（"Style guides for Google-originated open-source projects"），随后列出全部风格指南链接、附带工具（cpplint、google-c-style.el）、许可证说明与贡献方式。它完整覆盖了 What / Status / More info：读者看到的第一时间就知道"这是什么、能用什么、去哪里看细节"。READMEs.md 中"the file /README.md is rendered when you view the contents of the containing directory"所指的正是这个文件。
• cpplint 工具 cpplint/README：一份极简但信息完整的包级 README——说明这是"确保 C++ 文件遵循 Google C++ 风格指南的自动化检查器"（What）、给出运行方式./cpplint.py --help（More info/Usage）、说明单元测试文件 cpplint_unittest.py 可安全忽略（对终端用户的指引），最后附许可证。它示范了"最小可行 + 四要素齐备"的写法。

6.3 与 Markdown 格式规范的配合

best_practices 论述的是"写什么、何时写"，而 style.md 回答的是"怎么排版"。两者配合构成完整的文档工作流。style.md 中值得注意的通用建议包括：

• 文档布局：# 文档标题→ 简短引言（1–3 句，站在"完全新手的视角"写）→[TOC]→ 从 H2 开始的分节 →## See also杂项链接；
• 80 字符行宽：与代码习惯一致，便于工具链（如 Code Search）和既有评审文化复用；链接、表格、标题、代码块可豁免；
• 唯一且完整的标题名：标题锚点由标题自动生成，命名应自描述（如### Foo summary而非### Summary）；
• 优先 Markdown 而非 HTML：保持源码可读性与可移植性，参见 philosophy.md。

由此可以看到 docguide 三份文档（best_practices / READMEs / style）互为表里：best_practices 定战略（为什么、何时），READMEs 与 style 定战术（写什么、怎么写），共同构成一套完整的工程文档方法论。

七、实践路线图：把 Best Practices 应用到你的仓库

综合原文档与仓库实例，可将整套方法论落地为以下可执行清单：

1. 盘点（Audit）：列出仓库内所有文档，逐个做出 Keep / Delete 决策；先删除确定错误的，忽略含糊的。
2. 设最小集（Right-size）：只保留真正需要的——发布文档、API 文档、测试指南、README；其余一律不新增。
3. 同步更新（Couple with code）：把"改代码必须同 CL 改文档"设为评审硬性要求；reviewer 坚持 docstring、README 随代码更新。
4. 小步修剪（Trim frequently）：日常小批量删赘肉，阶段性地组织全员扫描。
5. 按谱系写作（Write at the right level）：内联注释讲"为什么"，方法注释讲"契约与用法"，类注释讲"概述 + 最简单示例优先"，README 讲"是什么 / 找谁 / 状态 / 去何处了解更多"。
6. 评审宽容（Review leniently）：对文档采用"宁好勿完美"标准，允许快速提交、渐进改进。
7. 持续迭代（Iterate）：让文档健康成为团队习惯与代码库文化的一部分。

这套流程在本仓库已有成熟示范：docguide 目录以五份短文覆盖文档方法论全貌，根 README 与 cpplint README 各司其职，philosophy 提供思想根基，style 提供格式约束——值得作为你所在团队文档治理的直接参考蓝本。

• 文档