best_practices.md

文档最佳实践

“简单直接地说出你的意图。” ——Brian Kernighan：《编程风格的要素》

最低可行文档

新鲜准确的少量文档要比一大堆处于各种失修状态下散乱的“文档”汇集更好。

编写简短有用的文档。删除所有不必要的内容，同时养成不断打磨和改进每个文档以适应不断变化的需求的习惯。活着但经常修剪的文件（就像盆景一样）最能发挥其作用。

本指南鼓励工程师为自己的文档担起责任，并以维护测试井井有条一样的热情保持最新。奋斗吧！

• 确定您真正需要的：发行文档，API文档，测试指南。
• 经常地每次小量地删除无用的内容。

文档和代码一起更新

在与代码更改相同的变更列表中更改文档。这可以使您的文档保持最新状态，也是向代码评审人解释您正在做什么的好地方。

优秀的审阅者至少可以坚持要求（python）文档字符串，（C++）头文件，README.md 文件和任何其他文档都随变更列表一起更新。

删除死文档

死文档是坏的，会导致误导和拖累，还会引起工程师的绝望和团队领导的懒惰。死文档在代码库中留下了混乱的先例。如果您的房屋整洁，大多数客人会自觉打扫卫生。

就像任何大型清理工程一样，你很容易被淹没在里面。如果您的文档状况不佳，按照这样的方式去改进：

• 慢慢来，文档健康是逐步积累的。
• 首先删除您确定是错误的内容，而忽略不清楚的内容。
• 让您的整个团队参与其中。花时间快速扫描每个文档并做出简单的决定：保留还是删除？
• 默认为删除或迁移后保留。别纠结，总有办法恢复的。
• 持续迭代。

追求好而不是完美

您的文档应该在合理的时间范围内尽可能地完善。 文档审查的标准与代码审查的标准不同。审阅者可以并且应该提出改进建议，但总的来说，作者应始终能够引用“良好胜于完美”的原则。 最好允许作者快速提交对文档有改进的更改，而不是强制进行几轮审核直到“完美”为止。文档从来都不是完美的，并且会随着团队学习他们真正需要写下来的东西而逐渐趋于完善。

文档是您代码的故事

即使您的代码通过了编译甚至测试覆盖率达到100%，也不能算完成了出色的代码。编写计算机可以理解的东西很容易，而写人类和计算机都可以理解的东西要难得多。 作为一名注重代码健康的工程师，您的任务是首先为人类编写代码，其次才是为计算机。文档是此技能的重要组成部分。

工程文档的范围很广，从简短的评论到详细的散文，不一而足：

1. 内联注释：内联注释的主要目的是提供代码本身无法包含的信息，例如这段代码为什么存在。

2. 方法和类注释：

   • 方法API文档：头文件 / Javadoc / docstring 注释，说明了方法做什么以及如何使用它们。本文档是您的代码必须如何行为的合同。目标读者是将来使用和修改您的代码的程序员。

     通常可以合理地说，此处记录的任何行为都应通过测试来验证。本文档详细介绍了该方法采用的参数，返回的内容，任何“陷阱”或限制，以及它可以引发的异常或可以返回的错误。 它通常不会解释代码为什么会表现出特定的方式，除非这与开发人员对如何使用该方法的理解有关。“为什么”说明适用于内联注释。 在编写方法文档时，请务实地思考：“这是一把锤子。您可以用它来砸钉子。”

   • 类/模块API文档：对类或整个文件的头文件/ Javadoc / docstring 注释。这种文档简要概述了类/文件的功能，并经常提供一些简短示例说明如何使用类/文件。

3. README.md：好的README.md 会将新用户引导到该目录，并指向更详细的说明和用户指南：

   • 此目录打算存放什么？
   • 开发人员应当首先查看哪些文件？有哪些文件是 API 吗？
   • 谁维护此目录，在哪里可以了解更多信息？

   参见README.md。