软件架构文档最小化的方法 -DEV

20-07-22 banq

许多软件开发人员会很快告诉您:

  • “我们很敏捷”
  • “我们认为工作软件胜于全面的文档”
  • “价值在于对话”
  • “代码就是文档”
  • “测试是文档”

代码是事实,而不是全部事实

正如Grady Booch会告诉您的那样,“代码是真理,而不是全部真理”。尽管我们绝对应该为高度模块化的代码而努力,并且命名要表达意图而不是依赖注释,但是代码不会告诉您以下内容:

  • 我们正在建造的东西的背景是什么?
  • 谁在使用项目/产品?
  • 它与我们工作的组织内部和外部的其他软件系统有什么接口?
  • 软件系统部署在哪里?
  • 我们如何支持它?
  • 是什么促使团队以他们的方式构建软件系统的驱动力?
  • 是什么导致早期决策被更改?
  • 等等

架构文档中描述您无法从代码中得到的

考虑到这一点,并记住时间是很宝贵的,这是我建议的一套最小的软件体系结构文档。

  • 一个系统上下文关系图
  • 一个容器图:“容器”类似于服务器端Web应用程序,单页应用程序,桌面应用程序,移动应用程序,数据库架构,文件系统等。本质上,容器是可单独运行/可部署的单元(例如,单独的进程空间) )来执行代码或存储数据。
  • 一个或多个部署图
  • 一些轻量级的Markdown / AsciiDoc文档(例如,软件指南arc42
  • 体系结构决策记录(ADR)

考虑这是一个起点,理想情况下,它应该与源代码一起存储。如果您需要一些代码级图来记录代码库的各个部分,请随时添加一些UML类图或序列图。如果需要记录业务流程,则添加一些UML活动图,或者看看ArchiMate。包括:实体关系模型,域模型,状态图,API定义等。

 

                   

猜你喜欢