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

 

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

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

對於這些決策，因爲咱們缺乏當時的上下文，只能盲目的接受和盲目的作出改變。

閒逛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

 

原文出處：https://www.cnblogs.com/xguo/p/11144324.html