利用建筑决策记录提高文档质量

即使对于经验丰富的开发人员来说，开始一个新项目也可能是一项艰巨的任务。你需要了解系统设计，理解代码库，以及所有内容如何映射到向用户展示的功能。

这是我们编写文档的主要原因之一。

目标是加快项目的进展，因为您越快了解系统，您就越快能够为其做出贡献。

拥有优秀的文档还有一个不太明显的效果。
开发人员在现有项目上投入精力就像一股清新的空气。了解项目背景信息，让他们能够从不同的角度看待它；这种视角可能会以你未曾察觉的方式帮助系统发展和改进。

事情是这样的，根据我的经验，我们很少记录系统的一个非常重要的方面：它的演变，它是如何变成现在这个样子的，以及哪些决策导致了它目前的状态。

如果没有文档来处理架构决策，新加入项目的开发人员会面临非常不利的处境。
他们很难理解为什么要这样做，更重要的是，很难知道是否可以更改。

你查看了一段代码/设计图/类图，但不太明白为什么要这么做。
你可能会想，换个方法会更好。
这种情况可能会演变成两种情况：

你觉得做这件事的人一定有充分的理由，只是你看不出来。你决定不去改变它。
你觉得做这件事的人根本就不知道。你用你认为更好的方法修改了它，在三次调试和两杯咖啡之后，你又把它恢复了。

这两种情况都会导致灾难。
第一种情况，团队可能会错过一些重大改进。第二种情况，你会浪费时间和精力，甚至可能影响到一些客户。

经过这个比较长的介绍，我希望我已经说服了你，我们需要一种更好的方法来记录驱动我们软件的进化决策。

这就是架构决策记录 (ADR) 的全部内容。

不良反应

ADR 定义了一种记录架构决策的方法，使读者能够追踪其演变过程。
这并不是什么新鲜事，而是一个相当古老的想法。我在网上找到的第一个参考资料是Michael Nygard
（《Release it!》一书的作者）于 2011 年发表的一篇文章。可惜的是，该页面似乎已被删除。

使用 ADR

将每个决定记录在案
保持记录版本与代码一起控制
让每条记录共享相同的模板
每次做出决定或撤销之前的决定时，都会创建另一个记录

就是这样。很简单。
对于包含记录或用于记录的模板的文件夹名称，没有标准或惯例。
话虽如此，有几种方案，但您可以自由使用最适合您的方案。
例如，我是这样做的：我在 git 仓库的根目录中
创建一个名为adr
的文件夹。如下所示：

/adr
  000_template
  001_use_springboot
  002_build_rpm_with_fpm
  003_revoke_decision_to_use_springboot
  004_use_XYZ_instead_of_springboot
/src
  /com
    ...

名为000_template的文件包含用于创建记录的模板。保存该模板很方便，这样可以通过复制模板文件来创建新记录。
我使用的模板如下：

## Title here
Date:

### Status
Accepted | Rejected | Suspended

### Context

### Decision

### Consequences

它非常简单，但我发现它非常有效。
其他文件以其内容命名。例如，002_build_rpm_with_fpm可能包含：

## build_rpm_with_fpm
Date: 2018, 19 Nov
### Status
Accepted
### Context
rpmbuild is a tool that builds an rpm given a spec file.  
It is pretty low level, so different solutions have emerged to abstract away some of the details.  
There are many solutions available in the wild.

### Decision
Use [fpm](https://github.com/jordansissel/fpm) to build the rpm.
The alternatives considered:  
#### RpmBuilder
__Pros:__
- Already wired with the internal tooling
__Cons:__
- Requires some heavy lifting to build the directory structure necessary to build the rpm
- Very poorly documented and it does not seem to be used

#### fpm   
__Pros:__
- Hide the details necessary to build the rpm
- Nice documentation
- Used by other teams
__Cons:__
- Some custom build logic is necessary to make it work in harmony with the build system. 

__Link:__ https://github.com/jordansissel/fpm
### Consequences
The package structure is intuitive and it is going to represent exactly the folder structure installed by the rpm.  
Build logic is very easy to understand and modify.

结论

使用 ADR 记录你的架构决策。这不仅能帮助项目成员，还能帮助你自己。正如一句名言所说：“如果你六个月或更长时间没看自己的代码，那它就像是别人写的一样。”

编码愉快！

其他资源

该图片由samuel在Pixabay上发布

文章来源：https://dev.to/napicella/improve-documentation-quality-in-4-mines-with-architectural-decision-records-g0h