美文网首页
敏捷开发,你的架构文档是怎么写的?

敏捷开发,你的架构文档是怎么写的?

作者: 土豆的奥特之父 | 来源:发表于2019-05-26 00:54 被阅读0次

每个系统都包含一系列架构决策,定义了设计和实现的边界和限制,
架构设计文档的核心是以某种方式的选型决策,而开发团队可能不太清楚这个决策背后的假设和思考。

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

闲逛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.mdNNNN 是一个单调的数字序列,例如 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

相关文章

  • 敏捷开发,你的架构文档是怎么写的?

    每个系统都包含一系列架构决策,定义了设计和实现的边界和限制,架构设计文档的核心是以某种方式的选型决策,而开发团队可...

  • 力软敏捷开发框架体验地址在哪里?如何体验?

    什么是敏捷开发框架? 力软敏捷开发框架使用当前主流的ASP.NET MVC开发技术,及B/S架构,并结合大量的...

  • XP学习笔记

    传统软件工程方法的文档辆过重?于是出现了 ? 敏捷开发 ? “轻量级”方法的软件开发方法?XP是敏捷开发的...

  • 敏捷开发中进度与文档的平衡

    最近和同事讨论敏捷开发如何在进度和文档之间找到平衡?居然发现大家理解各异。什么是敏捷开发?敏捷开发是否意味着省...

  • 怎么写用户故事?

    一,何为用户故事: 用户故事是敏捷开发里面的叫法; 传统需求文档就是类似瀑布开发等的叫法; 要用敏捷开发,就要写用...

  • 敏捷开发文档写多少,何时写?

    有一天我在会议室还没结束上一个会议,忽然电话会议呼进来,接进会议,感觉气氛有点不对劲。回到座位,问清楚缘由,原来是...

  • Scrum快速入门

    什么是敏捷开发? 敏捷开发(Agile Development)是一种以人为核心、迭代、循序渐进的开发方法。 怎么...

  • 敏捷开发

    什么是敏捷开发? 敏捷开发(Agile Development)是一种以人为核心、迭代、循序渐进的开发方法。怎么理...

  • 敏捷开发的PRD该怎么写

    一、为什么会有PRD 首先来说说为什么会有PRD文档。 1、稍微大一点的团队产品经理未必能向每个人传达产品需求,这...

  • 什么是敏捷开发?

    1.朋友,你听说过敏捷么? 3.设计也要介入敏捷流程? 4.敏捷跟文档是对立的? 5.我这有个几百亿的大项目,怎么...

网友评论

      本文标题:敏捷开发,你的架构文档是怎么写的?

      本文链接:https://www.haomeiwen.com/subject/qajvzqtx.html