敏捷開發，如何編寫架構文件

土豆的奧特之父發表於2019-07-06
敏捷架構

 

每個系統都包含一系列架構決策，定義了設計和實現的邊界和限制，

架構設計文件的核心是以某種方式的選型決策，而開發團隊可能不太清楚這個決策背後的假設和思考。

對於這些決策，由於我們缺少當時的上下文，只能盲目的接受和盲目的做出改變。

閒逛ThoughtWorks Radar偶然發現一個在17年和18年都被ADOPT（採用）的技術叫“ADR - Lightweight Architecture Decision Records”，輕量的架構決策記錄，針對演進式架構而提出的一種架構文件管理方法。

https://assets.thoughtworks.com/assets/technology-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) ）。

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)] <!-- optional -->
* Deciders: [list everyone involved in the decision] <!-- optional -->
* Date: [YYYY-MM-DD when the decision was last updated] <!-- optional -->

Technical Story: [description | ticket/issue URL] <!-- optional -->

## 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 <!-- optional -->

* [driver 1, e.g., a force, facing concern, …]
* [driver 2, e.g., a force, facing concern, …]
* … <!-- numbers of drivers can vary -->

## Considered Options

* [option 1]
* [option 2]
* [option 3]
* … <!-- numbers of options can vary -->

## 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 <!-- optional -->

* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
* …

### Negative Consequences <!-- optional -->

* [e.g., compromising quality attribute, follow-up decisions required, …]
* …

## Pros and Cons of the Options <!-- optional -->

### [option 1]

[example | description | pointer to more information | …] <!-- optional -->

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->

### [option 2]

[example | description | pointer to more information | …] <!-- optional -->

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->

### [option 3]

[example | description | pointer to more information | …] <!-- optional -->

* Good, because [argument a]
* Good, because [argument b]
* Bad, because [argument c]
* … <!-- numbers of pros and cons can vary -->

## Links <!-- optional -->

* [Link type] [Link to ADR] <!-- example: Refined by [ADR-0005](0005-example.md) -->
* … <!-- numbers of links can vary -->

注意，有很多項是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 a help 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 look for information about how to run a script.

Decision
Write usage documentation in comments in the source file.

Distinguish between documentation comments and normal comments. Documentation comments have two hash characters at the start of the line.

The adr help command can parse comments out from the script using the standard Unix tools grep and cut.

Consequences
No need to maintain help 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 work if any subcommands are not implemented as scripts that use '#' as a comment character.

小結

總結一下，越來越多的基於敏捷的專案開發模式，要求我們有演進式的架構設計眼光，因此我們也需要採用一種類似的技術，去有效的，敏捷的整理架構文件，去跟蹤記錄你或者你們團隊，曾經對一系列功能所做出的架構思考和取捨權衡的過程。

參考

  1. https://adr.github.io/ Homepage of the ADR
  2. https://www.thoughtworks.com/radar/techniques/lightweight-architecture-decision-records
  3. https://www.hascode.com/2018/05/managing-architecture-decision-records-with-adr-tools/ Managing Architecture Decision Records with ADR-Tools
  4. https://resources.sei.cmu.edu/asset_files/Presentation/2017_017_001_497746.pdf
  5. https://agilemanifesto.org
 

相關文章