您对文档驱动开发了解多少？

为什么我们在开发过程中甚至需要任何文档？

代码记录本身的这个语句怎么样？

让我们考虑最常见的情况：系统的代码（无论是程序、项目还是产品）都需要经过很长一段时间才能编写完成，并且团队在此过程中逐渐发生变化，随着开发人员的离开，他们对系统有一定的了解。

在这种情况下我们能做什么？

最简单的答案是编写一个规范，捕获所有实现细节，以确保系统满足原始要求。

但是，这样的文档很难提前写好，而且在开发过程中，一些实施细节可能会发生变化（适应市场/对机械师的新要求等）。那么，我们可以想出什么办法来提高巴士系数呢？

让我们尝试遵循可能是解决上述问题的可能解决方案之一的流程。

要求和 RFC

首先，我们需要根据利益相关者的需求描述初始设计，并将其记录下来。之后，可以将此文档与其他团队共享，并征求他们的反馈：要求实现某些功能、对初始设计发表评论、修复某个接口等。这样的文档可以称为RFC 。

RFC ，即“征求意见稿”，是一份分发给相关方（包括开发人员、架构师和其他团队）的文档，用于收集反馈、评论和建议。它不如规范详细，仅包括初始问题、任务和解决方案领域。它更灵活，允许主动接受设计变更，确保对任务有深入的理解，并促进高质量和深思熟虑的决策。

设计承诺和 ADR

好的，我们已经定义了技术要求并收集了其他团队的要求。下一步是什么？

在此阶段，需要确定系统设计及其将执行的所有主要功能。为此，我们编写了ADR 。

ADR ，即“架构决策记录”，是一份记录软件开发过程中做出的重要架构决策的文档。每份ADR都描述了一个特定的高级架构决策、其背景、考虑的替代方案、做出的决策以及选择这些特定细节而非其他细节的动机。

这样的文档可以让每个团队成员（以及其他团队）了解设计所依据的原则和价值观。如果几年后有新开发人员加入团队并问：“你为什么要这样做？”，可以向他们展示这份文档，它将回答他们所有的问题。

规格

现在是时候编写代码及其规范了。在此阶段，我们会彻底研究每个功能，同时将所有信息和实现细节汇编成一份特殊文档。这份文档应反映系统当前的低级要求。

重点是：在软件生命周期中，这样的规范可能会发生很大变化，这没关系。但是，仍然保留原始设计和架构非常重要，以防止代码库变得难以管理。

测试计划

为什么需要它？至关重要的是，测试计划的制定不应基于按照规范编写的代码（我们编写代码并测试这些代码，以便它们通过），而应基于包含必须正确处理的关键场景的设计。您还可以将这样的测试计划提交给其他团队进行审查（用于集成或仅用于额外测试），这也非常方便，从而明确系统在不同情况下的行为方式。

它包括什么？

• 所有可能的系统运行场景

  • 快乐之路
  • 悲傷之路
  • 错误处理

• 系统运行期间必须保持的所有可能的不变量

• 验收测试在启动时检查系统状态（应考虑环境，例如网络上的数据）

  
  

我们已经完成了设计，编写了代码和规范，并编制了测试计划。听起来已经很可靠了！但我们还能添加什么呢？

部署计划

在某种程度上，可能需要这样的计划来提高巴士系数并创造任何团队成员都可以部署系统并验证其状态的条件。

为什么我们不能没有它？我们可以，但在现实世界中，大型团队中有许多人负责系统的不同部分，部署过程可能完全委托给 DevOps。这有什么问题，既然我们已经编写了测试，将它们放入 CI，并检查了漏洞，我们还需要其他什么吗？也许不需要，但测试通常不考虑系统的当前状态，测试结果也不完全符合我们的要求。

部署计划可能包含以下内容：

• 部署所需执行操作的完整描述
• 部署参数：
  • 环境变量
  • 初始状态
  • 发射参数
• 如果任何步骤出现问题，应制定计划
• 如果可能的话，备用计划
• 当无法继续部署时系统必须处于的必要状态
• 部署后需要执行的操作
  • 通知其他团队
  • 如果需要，启用必要的集成

没什么复杂的，对吧？针对特定更新拥有这样的文档可以显著提高巴士系数并避免对特定个人的依赖。这不正是我们想要的吗？

结论

在软件开发过程中，不仅要编写代码，还要创建文档以确保在开发的所有阶段都能理解和保持一致性，这一点很重要。文档可能就是代码本身，但经验表明，文档对于维护系统的质量、稳定性和未来的可扩展性非常重要，尤其是在开发过程中团队发生变化时，以及项目发展并适应新要求时。

文档包括RFC （征求意见书）、 ADR （架构记录）、规范、测试计划、部署计划等。这将保证团队中知识的保留，简化新员工融入项目的过程，并提高系统的整体可靠性和抗变化能力。