文档化我们的代码

每个人都喜欢有帮助的、清晰的文档，但当文档过时且与当前代码库无关时，情况就不同了。软件中有一个普遍原则：两个相关概念之间的分离越大，它们带来的痛苦就越多。举个例子，想象一下一些读取某种晦涩文件格式的代码，没有人记得这种格式。只要你在读取这种旧格式的文件，一切都很好。然后你升级了应用程序，旧的文件格式不再受支持，一切都崩溃了。代码与这些旧文件中的数据内容分离了。文件没有改变，但代码改变了。我们甚至没有意识到发生了什么。

文档也是如此。最糟糕的文档通常包含在最华丽的文档中。这些文档是在代码创建很久之后由具有不同技能（如文案写作、平面设计等）的团队编写的。当时间紧迫时，文档更新是发布中首先被放弃的事情。

解决方案是让文档更接近代码。让更接近代码的人编写文档，他们知道代码的详细工作原理。让需要直接使用该代码的人阅读文档。

与极限编程（XP）的所有其他方面一样，最明显的主要胜利是让文档如此接近代码，以至于它就是代码的一部分。这包括使用我们的良好设计基础编写清晰的代码，而我们的测试套件也起着关键作用。

我们的 TDD 测试是代码，而不是手动测试文档。它们通常使用与主代码库相同的语言和仓库编写。它们将由编写生产代码的同一批人——开发者——编写。

测试是可执行的。作为一种文档形式，你知道可以运行的东西必须是最新的。否则，编译器会抱怨，代码将无法运行。

测试还形成了如何使用我们生产代码的完美示例。它们明确定义了如何设置代码、它有哪些依赖项、它有哪些有趣的方法和函数、它的预期效果是什么，以及它将如何报告错误。你想知道的关于该代码的一切都在测试中。

起初这可能令人惊讶。测试和文档通常不会混淆。但由于 TDD 的工作方式，两者之间存在巨大的重叠。我们的测试是对代码应该做什么以及我们如何让它为我们工作的详细描述。