“简单直接地表达你的意思。” - Brian Kernighan
目录
一套精简且准确的文档胜过大量状态各异的“文档”。
编写简短而有用的文档。 删掉一切不必要的东西，包括过时、不正确或冗余的信息。 还要养成不断改进每个文档以适应你不断变化的需求的习惯。 文档在保持活跃的同时，经常修剪才能达到最佳效果，就像盆景一样。
另请参阅 这些敏捷文档最佳实践。
在代码更改的同一个 CL 中更改你的文档。 这样可以保持你的文档新鲜，也是向你的审查者解释你在做什么的好地方。
一个好的审查者至少可以坚持 docstrings、头文件、README.md 文件和任何其他文档与 CL 一起更新。
过时的文档是糟糕的。 它们会误导，它们会减慢速度，它们会激起工程师的绝望和团队负责人的懒惰。 它们为在代码库中留下烂摊子开创了先例。 如果你的家是干净的，大多数客人即使没有被要求也会是干净的。
就像任何大型清洁项目一样，很容易感到不知所措。 如果你的文档状况不佳
文档是一门艺术。 没有完美的文档，只有经过验证的方法和审慎的指导方针。 请参阅 更好胜于最好。
编写出色的代码并不会在你的代码编译完成，甚至测试覆盖率达到 100% 时结束。 编写计算机可以理解的东西很容易，但编写人类和计算机都可以理解的东西要困难得多。 你作为一名注重代码健康的工程师的任务是首先为人类编写，其次为计算机编写。 文档是这项技能的重要组成部分。
工程文档的范围从简洁的注释到详细的散文
有意义的名称： 好的命名允许代码传递原本会降级为注释或文档的信息。 这包括所有级别的可命名实体，从局部变量到类、文件和目录。
内联注释： 内联注释的主要目的是提供代码本身无法包含的信息，例如代码存在的原因。
方法和类注释:
方法 API 文档： 说明方法的作用以及如何使用它们 的header / Javadoc / docstring 注释。 此文档是你的代码必须如何表现的合同。 目标受众是将来会使用和修改你的代码的程序员。
通常可以合理地说，此处记录的任何行为都应该有一个测试来验证它。 此文档详细说明了该方法采用的参数、它返回的内容、任何“陷阱”或限制，以及它可以抛出的异常或它可以返回的错误。 它通常不会解释代码以特定方式运行的原因，除非这与开发人员理解如何使用该方法相关。 “为什么”的解释用于内联注释。 在编写方法文档时，请从实际角度考虑：“这是一把锤子。 你用它来敲钉子。”
类/模块 API 文档： 类或整个文件 的header / Javadoc / docstring 注释。 此文档简要概述了该类/文件的作用，并且通常提供了一些如何使用该类/文件的简短示例。
当有几种不同的使用类的方法（一些高级，一些简单）时，示例尤其相关。 始终首先列出最简单的用例。
README.md： 好的 README.md 将新用户定向到目录，并指向更详细的说明和用户指南
请参阅 README.md 指南。
docs： 一个好的 docs 目录的内容解释了如何
设计文档、PRD： 一个好的设计文档或 PRD 详细讨论了提议的实现，目的是收集对该设计的反馈。 但是，一旦实现了代码，设计文档应作为这些决策的档案，而不是半正确的文档（它们经常被误用）。
其他外部文档： 一些团队在与代码分开的其他位置（例如 Google Sites、Drive 或 wiki）维护文档。 如果你确实在其他位置维护文档，你应该从你的项目目录中清楚地指向这些位置（例如，通过从你的项目的 README.md 添加到该位置的明显链接）。
不要编写你自己的常用 Google 技术或流程指南。 请链接到它。 如果该指南不存在或严重过时，请将你的更新提交到相应的目录或创建包级别的 README.md。 承担所有权并且不要害羞： 其他团队通常会欢迎你的贡献。