软件架构设计---软件架构文档化

软件架构文档化

记录软件架构的活动就是架构编档过程，也就是架构的文档化。它包含两个方面：一是过程，编档过程能促使架构设计师进一步思考，使得架构更加完善；二是结果，描述架构的文档将作为架构开发的成果，供项目关系人使用。

1．架构文档的使用者

架构文档的使用者是架构的项目关系人。编写技术文档（尤其是软件架构文档）最基本的原则之一是要从读者的角度来编写，易于编写但很难阅读的文档是不受欢迎的。

架构的主要用途是充当项目关系人之间进行交流的工具，文档则促进了这种交流—— 架构项目关系人希望从架构文档中获得自己所关心的架构信息，如：系统实现人员希望文档提供关于开发活动的不能违反的限制及可利用的自由；测试人员和集成人员希望能从文档中得到必须组合在一起的各部分，并以此得到一个正确的测试黑箱；项目经理希望根据所确定的工作任务组建开发小组，规划和分配项目资源。

2．合理的编档规则编写架构文档和编写其他文档一样，必须遵守一些基本规则，这里将任何软件编档（包括软件架构编档）的规则归纳为 7 条：

（1）从读者的角度编写文档。

（2）避免出现不必要的重复。

（3）避免歧义。

（4）使用标准结构。

（5）记录基本原理。

（6）使文档保持更新，但更新频率不要过高。

（7）针对目标的适宜性对文档进行评审。

3．视图编档

视图是最重要的软件架构编档概念，本书将在 9.11 节中专门讨论架构的视图。视图的概念为架构设计师提供了进行软件架构编档的基本原则。架构文档化就是将相关视图编成文档，并补充多个视图的关联关系。

视图编档的组织结构（内容及编排次序、大纲）虽然目前还没有工业标准模板，研究者（Bachmann 等人）提出的文档组织结构包含 7 个部分，如图 9-18 所示。

（1）视图概述：对系统进行概括性的描述，包含视图的主要元素和元素间的关系（但并不包含所有元素和元素间的关

系，如：与错误处理相关的内容可以放在支持文档中）。主要表示可用多个形式：图形、表格、文本，通常用图形形式，使用UML 语言来描述。

（2）元素目录：对主要表示中所描述的元素及其关系进行详细描述，包括：元素及其属性、关系及其属性、元素接口、元素行为。

这部分是文档的主要组成部分，其中要注意：

—对元素及其协同工作的行为进行编档，如用UML 的顺序图和状态图描述行为；
—对接口进行编档，图9-19 说明了这部分的内容。

（3）上下文图：用图形展示系统如何与其环境相关。

（4）可变性指南：描述架构的可变化点，如在软件产品线中，产品线架构通过变化，适用于多个系统，因此，文档中应包含这些变化点，如各系统要做出选择的选项、做出选择的时间。

（5）架构背景：为架构的合理性提供足够的、令人信服的论据。包括：基本原理、分析结果及设计中所反映的假定。

（6）术语表：对文档中每个术语进行简要说明。

（7）其他信息：描述不属于架构方面的必要信息，如管理信息（创作者、配置控制数据及变更历史）。

4．跨视图文档

软件架构由多个视图文档来反映，按前面所述的要求完成每个视图的文档后，需要对这些文档进行一个整体的“打包”工作，这就是跨视图文档。它包括如下内容：

（1）文档有哪些内容，它们是如何组织的：视图目录（含哪些视图）；视图模板（即前面描述的视图文档，企业可以通过规范化来定义统一的、公共的视图模板）。

（2）架构概述：它描述系统的目的、视图之间的关联、元素表及索引、项目词汇。

（3）为什么架构是这样的（基本原理）：跨视图基本原理解释了整体架构实际上是其需求的一个解决方案。即解释了做出决策的原因、方案的限制、改变决策时的影响及意义。

5．使用 UML

UML已经成为对软件架构进行文档化的事实上的标准表示法。在视图文档的组织结构中，UML 主要用于表示元素或元素组的行为。

6．软件架构重构

前面已论述了架构编档，即在架构设计时完成编档工作。但是还有另外一种情况：系统已经存在，但不知其架构，即架构没有通过文档很好地保留下来（文档的缺失/失效）。如何维护这样的系统并管理其演变？其关键就是要找到软件架构，软件架构重构就是研究解决这一问题的方法，它是反向工程之一。

架构重构需要工具的支持，但任何一个工具或工具集对架构重构都是不够的。因为：

工具往往是面向特定语言的；
数据提取工具经常返回不完整的或错误的结果，因此，应在多个工具提供的结果间进行补充、验证和判断；
重构的目的（文档的用途）不同，决定了需要提取什么数据，这反过来影响了工具的选择。以此为原则，就是架构重构的工作台方法，如 SEI 开发的 Dali。

软件架构重构由以下活动组成，这些活动以迭代方式进行，如图 9-20 所示。

（1）信息提取（View Extraction）。可以使用各种工具进行信息提取，如解析器、语法分析器等；可以利用 build 和 makefile 文件中关于模块的依赖关系；可以从源代码、编译时制品和设计制品中提取静态信息；可以使用分析工具提取动态信息。

（2）数据库构造（Database Construction）：将提取的信息转化为标准的形式，并置于数据库中。

（3）视图融合（View Fusion）：将数据库中的信息组合在一起，生成该架构的一个内聚的视图。

（4）重构（Reconstruction）：构建数据抽象和各种表示以生成架构表示，主要由两个活动组成：可视化和交互、模式定义和识别。最后生成需要的架构文档（Documentation）。

上述过程中，架构是由重构人员通过对系统做出一组假定来获得，为了最有效地生成这些假定并对其进行验证，必须让熟悉系统的人参与此项工作，包括过去参与系统开发的人员或现在正在对其进行维护的人员。

软件架构设计---软件架构文档化相关推荐

软件架构设计---软件架构概述
像学写文章一样,在学会字.词.句之后,就应上升到段落,就应追求文章的"布局谋篇",这就是架构.通俗地讲,软件架构设计就是软件系统的"布局谋篇". 人们在软件工程 ...
(软考笔记) —— 系统架构设计师 - UML建模与架构文档化
文章目录 UML建模与架构文档化 UML 现状与发展 UML起源 UML 体系结构演变 UML 的应用与未来 UML基础概述用例和用例图交互图类图和对象图状态和活动图状态图活动图构件图 ...
uml具有多种视图_UML建模与架构文档化
UML(统一建模语言) 是用元模型描述的,元模型是4层元模型体系结构模式中的一层.此模式的其他层次分别是元-元模型层.模型层和用户对象层. 在原模型层,UML元模型又被分解为三个子逻辑包:基础包(核 ...
使用 Swagger 文档化和定义 RESTful API
大部分 Web 应用程序都支持 RESTful API,但不同于 SOAP API--REST API 依赖于 HTTP 方法,缺少与 Web 服务描述语言(Web Services Descript ...
文档化Python代码完全指南（翻译）
阅读代码比编写代码更多,有良好丰富文档的项目会吸引更多人使用和参与开发贡献.本教程旨在详细阐述如何将 Python 代码实现"文档化",介绍了注释用法.类型提示.文档字符串.在项目 ...
华为19级专家10年心血终成百页负载均衡高并发网关设计实战文档
负载均衡(LoadBalance)的字面意思是将工作负载分担到多个工作单元上进行执行,它建立在现有网络结构之上,是构建分布式服务.大型网络应用的关键组件. 近十几年来,负载均衡技术层出不穷,令人眼花缭 ...
华为19级大佬10年心血终成百页负载均衡高并发网关设计实战文档
说在前面的话负载均衡(LoadBalance)的字面意思是将工作负载分担到多个工作单元上进行执行,它建立在现有网络结构之上,是构建分布式服务.大型网络应用的关键组件. 近十几年来,负载均衡技术层出不 ...
互联网产品设计常用文档类型-BRD、MRD、PRD、FSD
互联网产品设计常用文档类型-BRD.MRD.PRD.FSD 摘自:互联网产品设计常用文档类型-BRD.MRD.PRD.FSD 2017-03-16 1 BRD Business Requirement ...
数据库设计文档化---详细文档
因为不够详细的设计文档很可能让设计人员的电话打爆,让开发人员瞎蒙某些字段的含义. 数据库设计文档怎样才算写的详尽呢? 下面我们以物理设计文档为例,讨论如何书写详尽的数据库文档. 1.基本的设计需要.如 ...
软件架构设计---软件架构评估
软件架构评估软件架构评估是在对架构分析.评估的基础上,对架构策略的选取进行决策.它也可以灵活地运用于对软件架构进行评审等工作中. 1 软件架构评估的方法业界已开发出多种软件架构评估的方法, ...

软件架构设计---软件架构文档化

软件架构设计---软件架构文档化相关推荐

最新文章

热门文章