软件架构文档的极简方法

“我们应该写多少文档？”这个问题最近经常出现，这可能是由于团队正在审视业务连续性计划，以及远程办公的增多所致。许多软件开发人员会很快告诉你：

• “我们很敏捷”
• “我们重视可运行的软件而不是详尽的文档”
• “价值在于对话”
• “代码就是文档”
• “测试就是文档”

代码是真理，但不是全部真理

正如Grady Booch所说，“代码是真理，但不是全部真理”。虽然我们确实应该努力实现高度模块化的代码，并且命名能够表达意图而不是依赖注释，但代码并不能告诉你以下信息：

• 我们正在构建的东西的背景是什么？
• 使用该项目/产品的人是谁？
• 它与我们工作的组织内部和外部的其他软件系统有哪些接口？
• 软件系统部署在哪里？
• 我们如何支持它？
• 是什么驱动因素促使团队以他们的方式构建软件系统？
• 是什么导致早期决定发生改变？
• ETC

描述你无法从代码中获得什么

考虑到这一点，并记住时间是宝贵的，这是我对一套最少的软件架构文档的建议。

• 系统环境图
• 容器图
• 一个或多个部署图
• 一些轻量级的 Markdown/AsciiDoc 文档（例如软件指南或arc42）
• 架构决策记录（ADR）

将此视为起点，理想情况下应将其与源代码一起存储。如果您需要一些代码级图表来记录代码库的某些部分，请随意添加一些 UML 类图或序列图。如果您需要记录业务流程，请添加一些 UML 活动图，或者可以参考 ArchiMate。此外，还可以添加线框图、实体关系模型、领域模型、状态图、API 定义等。

概括

尽管“代码和测试就是文档”这样的说法不一定是错误的，但我们仍然应该努力添加一些更高层次的内容，描述我们无法轻易从代码中获得的内容。