文档最佳实践（Google 风格指南）
原文链接：google.github.io/styleguide/…
“言简意赅，直抒己见。” —— Brian Kernighan
目录
1. 最小可行文档
少量新鲜、准确的文档，胜过一大堆处于各种“半残”状态的“文档”。
写短小、有用的文档。删掉一切不必要的内容，包括过时、错误或冗余的信息。养成习惯，持续打磨和优化每份文档以适配变化中的需求。文档最好像盆景一样：保持鲜活，并经常修剪。
另见 敏捷文档最佳实践。
2. 与代码同步更新文档
在提交代码变更的同一份 CL 里修改文档。这样文档才能保持新鲜，也是向评审者说明你在做什么的好地方。
好的评审者至少会要求：docstring、头文件、README.md 以及其它相关文档随 CL 一起更新。
3. 删除失效文档
失效文档有害：误导读者、拖慢节奏、让工程师沮丧、让团队负责人懈怠，还会为在代码库里留下烂摊子开先例。家里干净，客人多半也会自觉保持干净。
就像任何大扫除一样，很容易被压垮。如果文档状况很差：
- 放慢节奏，文档健康是日积月累的事。
- 先删掉你确定错误的内容，拿不准的先别动。
- 让整个团队参与，花时间快速扫一遍每份文档，做一个简单决定：保留还是删除？
- 迁移时默认删除或弃用；掉队的内容总可以再找回来。
- 反复迭代。
4. 宁要好，不求完美
文档是一门艺术。没有完美的文档，只有经过验证的方法和审慎的指南。参见 Better is better than best。
5. 文档是代码的故事
写出优秀代码并不止于“能编译”甚至“测试覆盖 100%”。写一段机器能懂的东西不难，难的是写出一段人和机器都能懂的东西。作为注重代码健康的工程师，你的使命是先为人写，再为机器写。文档是这项能力的重要一环。
工程文档有一整条光谱，从简短的注释到详尽的说明：
- 有意义的命名：好的命名能让代码自己传达信息，否则这些信息只能写在注释或文档里。这包括各个层级的可命名实体：局部变量、类、文件、目录。
- 行内注释：行内注释的主要目的是提供代码本身无法表达的信息，例如这段代码为什么存在。
- 方法与类注释：
- 方法 API 文档：头文件 / Javadoc / docstring 中说明方法做什么、怎么用。这类文档是代码行为契约。受众是将来会使用和修改你代码的程序员。通常可以要求：这里文档化的行为都应有测试验证。文档应说明：参数、返回值、“坑”或限制、可能抛出的异常或返回的错误。一般不必解释“为什么这样实现”，除非对开发者理解用法有帮助；“为什么”留给行内注释。写方法文档时想得实际一点：“这是一把锤子，用来钉钉子。”
- 类 / 模块 API 文档：类或整个文件的头文件 / Javadoc / docstring。简要概述类/文件做什么，并常附带几个简短使用示例。当类有多种用法（有的简单、有的高级）时，示例尤其有用。始终把最简单的用法写在最前面。
- README.md：好的 README.md 能帮新用户快速了解该目录，并指向更详细的说明和用户指南：
- 这个目录打算放什么？
- 开发者应先看哪些文件？有没有是 API？
- 谁在维护这个目录，哪里可以了解更多？ 参见 README.md 指南。
- docs 目录：好的 docs 目录应说明如何：
- 上手使用相关 API、库或工具。
- 运行测试。
- 调试输出。
- 发布产物。
- 设计文档、PRD：好的设计文档或 PRD 会详细讨论拟议实现，以便收集对设计的反馈。但代码实现后，设计文档应作为这些决策的档案，而不是半对半错的“活文档”（后者常被误用）。
- 其它外部文档：有些团队在代码库之外维护文档（如 Google Sites、Drive、wiki）。若你也在别处维护文档，应在项目目录里明确指向这些位置（例如在项目的
README.md里加上醒目的链接）。
6. 重复是魔鬼
不要为通用的技术或流程另写一份自己的指南，链到已有文档即可。若指南不存在或严重过时，向对应目录提交更新，或写一份包级 README.md。主动负责、不必害羞：其它团队通常会很欢迎你的贡献。
本站为开源项目。改进本页。
