为什么文档很重要

我们为什么要创建文档？难道我们的代码或测试还不够文档化吗？这些想法有一定的道理，我们将在本节中进一步讨论这个话题。然而，多年来，无数开发人员从未停止过创建无数文档，这其中一定有什么原因。

我们之所以创建文档，是因为我们可以让其它人更轻松地使用我们的软件。这与上下文有关，而上下文并不能从阅读几个类的代码中轻易提取出来。文档通常不仅涉及 "是什么 "或 "如何做"，还涉及 "为什么"。

了解导致决策的动机或外部因素，对于理解和接受项目为何以某种方式构建至关重要。例如，你可能会抱怨你的前同事从外部文件传输协议（FTP）服务器下载逗号分隔值（CSV）文件时采用了一种蹩脚的、由 cronjob 触发的下载方式，除非你从文档中了解到客户根本无法在项目截止日期前提供一个可呈现状态传输（REST）应用编程接口（API）端点来交付数据。

新同事开始参与你的项目时，肯定会很高兴至少有一些文档可以阅读，而不需要向其它开发人员询问（可能还会打扰他们）每一个小问题。我们也不要忘记未来的自己，他们已经好几个月没有接触过这个项目了，现在必须修复一个关键的错误。如果我们知道过去的自己是怎么做的…​…​以及为什么。

如果你创建的是开放源码软件（OSS），那么文档同样重要。如果你需要评估多个第三方软件包，以决定在某个项目中使用哪一个，那么如果某个软件包有很好的文档，就更有可能得到考虑。如果你在一个工具上投入了无数的时间，却因为它没有或没有良好的文档而无人使用，那岂不是太可惜了吗？

最后，如果你以软件开发为生，那么你应该把编写文档视为专业开发人员的职责之一。这就是你的报酬。

提到文档，我们首先想到的通常是用户文档：冗长、难读、枯燥的文字，讲述如何使用软件产品的每一个功能，例如文字处理器。当然，这些文档的存在是有道理的，但在本书中我们不应该对此感兴趣，因为这些文档通常不是由开发人员编写的（也不是为开发人员编写的）。

软件文档是一个涉及面很广的领域，因此，本章无法对其进行全面介绍。我们更希望将重点放在那些能在开发过程中为你提供支持并使你能编写出简洁代码的文档上，下面的列表并不详尽：

在下一节中，我们将仔细研究如何让编写这类文档变得更容易。