敏捷开发，如何编写架构文档 - 好文

每个系统都包含一系列架构决策，定义了设计和实现的边界和限制，

架构设计文档的核心是以某种方式的选型决策，而开发团队可能不太清楚这个决策背后的假设和思考。

对于这些决策，由于我们缺少当时的上下文，只能盲目的接受和盲目的做出改变。

闲逛ThoughtWorks Radar偶然发现一个在17年和18年都被ADOPT（采用）的技术叫“ADR - Lightweight
Architecture Decision Records”，轻量的架构决策记录，针对演进式架构而提出的一种架构文档管理方法。

https://assets.thoughtworks.com/assets/technology-radar-vol-18-cn.pdf
<https://links.jianshu.com/go?to=https%3A%2F%2Fassets.thoughtworks.com%2Fassets%2Ftechnology-radar-vol-18-cn.pdf>

ADR
敏捷开发和ADR

敏捷宣言说：“可以工作的软件，强过全面的文档”
(agile manifesto: Working software over comprehensive documentation)

--- 意思不是说不需要文档！

特别是敏捷类型的项目，软件架构需要适应新的业务、市场的变化，架构技术重要的决策是如何做出的，为什么这么选择，背后有怎样的假设。

所以，主要的问题是架构的文档形式和内容，架构文档需要与项目的状态保持紧密的关系，并且简洁，明了，便于维护和阅读，不然，架构的文档就没有人看，更不会有人去更新他。

什么是ADR

接下来我们就来简单看一下什么是ADR，如何解决篇头提出的几个疑虑。

ADR，先来看一下什么是AD（Architecture Decision）？，

在《Documenting Architecture Decisions》一文中说道架构文档应该关注和收集的内容包括：“affect the
structure, non-functional characteristics, dependencies, interfaces, or
construction techniques”。

因此，架构决策，是一个软件设计的选择，涵盖了功能性和非功能性所需要的重要架构选型和设计，系统架构的质量是可以被衡量的（Architecturally
Significant Requirement (ASR)
<https://links.jianshu.com/go?to=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FArchitecturally_significant_requirements>
）。

Architectural Decision Record
(ADR)是一个单一的架构决策的记录文件，例如架构师所做出的架构决策思考，或者架构设计会要的记录等，而 ADRs
则是维护了一系列架构记录文件集合（ARD），通常存储在项目的 doc/adr 目录下，文件名的格式形如：
adr-NNNN-title-with-dashes.md ，或者 NNNN-title-with-dashes.md，NNNN 是一个单调的数字序列，例如
0001.

注意，当某个决策被废除，这个旧的ADR文件应该保留，只是做个标记，表示被取代，因为它也是曾经决策思考的结果。

ADR文件的结构：
# [short title of solved problem and solution] * Status: [proposed | rejected
| accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] * Deciders: [list everyone involved in the decision] * Date: [YYYY-MM-DD when the decision was last updated]
Technical Story: [description | ticket/issue URL] ## Context
and Problem Statement [Describe the context and problem statement, e.g., in
free form using two to three sentences. You may want to articulate the problem
in form of a question.] ## Decision Drivers * [driver 1, e.g.,
a force, facing concern, …] * [driver 2, e.g., a force, facing concern, …] * …
 ## Considered Options * [option 1] *
[option 2] * [option 3] * … ## Decision
Outcome Chosen option: "[option 1]", because [justification. e.g., only option,
which meets k.o. criterion decision driver | which resolves force force | … |
comes out best (see below)]. ### Positive Consequences *
[e.g., improvement of quality attribute satisfaction, follow-up decisions
required, …] * … ### Negative Consequences * [e.g.,
compromising quality attribute, follow-up decisions required, …] * … ## Pros
and Cons of the Options ### [option 1] [example | description
| pointer to more information | …] * Good, because [argument
a] * Good, because [argument b] * Bad, because [argument c] * … ### [option 2] [example | description | pointer to
more information | …] * Good, because [argument a] * Good,
because [argument b] * Bad, because [argument c] * … ### [option 3] [example | description | pointer to more
information | …] * Good, because [argument a] * Good, because
[argument b] * Bad, because [argument c] * … ## Links * [Link type] [Link to ADR]  * …
注意，有很多项是optional 的，根据情况，自行取舍。

一个例子：（doc/adr/0005-help-comments.md）
5. Help comments Date: 2016-02-13 Status Accepted Amended by 9. Help scripts
Context The tool will have ahelp subcommand to provide documentation for users.
It's nice to have usage documentation in the script files themselves, in
comments. When reading the code, that's the first place to lookfor information
about how to run a script. Decision Write usage documentationin comments in the
source file. Distinguish between documentation comments and normal comments.
Documentation comments have twohash characters at the start of the line. The adr
helpcommand can parse comments out from the script using the standard Unix
tools grep and cut. Consequences No need to maintainhelp text in a separate
file. Help text can easily be kept up to date as the script is edited. There's
no automated check that the help text is up to date. The tests do not work well
as documentation for users, and the help text is not easily cross-checked
against the code. This won't workif any subcommands are not implemented as
scripts that use'#' as a comment character.
小结

总结一下，越来越多的基于敏捷的项目开发模式，要求我们有演进式的架构设计眼光，因此我们也需要采用一种类似的技术，去有效的，敏捷的整理架构文档，去跟踪记录你或者你们团队，曾经对一系列功能所做出的架构思考和取舍权衡的过程。

参考

* https://adr.github.io/
<https://links.jianshu.com/go?to=https%3A%2F%2Fadr.github.io%2F> Homepage of
the ADR
*
https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records

<https://links.jianshu.com/go?to=https%3A%2F%2Fwww.thoughtworks.com%2Fradar%2Ftechniques%2Flightweight-architecture-decision-records>
*
https://www.hascode.com/2018/05/managing-architecture-decision-records-with-adr-tools/

<https://links.jianshu.com/go?to=https%3A%2F%2Fwww.hascode.com%2F2018%2F05%2Fmanaging-architecture-decision-records-with-adr-tools%2F>
Managing Architecture Decision Records with ADR-Tools
*
https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf
<https://links.jianshu.com/go?to=https%3A%2F%2Fresources.sei.cmu.edu%2Fasset_files%2FPresentation%2F2017_017_001_497746.pdf>
* https://agilemanifesto.org
<https://links.jianshu.com/go?to=https%3A%2F%2Fagilemanifesto.org>

热门工具换一换