系统架构设计笔记（66）—— 配置管理与文档管理

た入场券 2022-11-25 13:18 195阅读 0赞

随着软件规模和复杂性的增大，许多大型开发项目往往都会延迟和超出预算，软件开发不得不直面越来越多的问题，表现为开发的环境日益复杂，代码共享日益困难，需跨越的平台增多；软件的重用性需要提高；软件的维护越来越困难。

为了解决这些问题，作为控制软件系统一系列变化的学科，软件配置管理（ Software Configuration Management ， SCM ）应运而生。其主要作用是通过结构化的 、 有序化的 、 产品化的管理软件工程的方法来维护产品的历史，鉴别和定位产品独有的版本，并在产品的开发和发布阶段控制变化；通过有序管理和减少重复性工作，配置管理保证了生产的质量和效率；它涵盖了软件生命周期的所有领域并影响所有数据和过程。作为软件开发中一个重要过程，实现在有限的时间和资金内，满足不断增长的软件产品质量要求，软件配置管理已经逐渐受到各类软件企业的重视。

## 1 软件配置管理的概念 ##

对于软件配置管理， IEEE 给出了一个定义： SCM 是指在软件系统中确定和定义构件（源代码 、 可执行程序 、 文档等），在整个生命周期中控制发布和变更，记录和报告构件的状态和变更请求，并定义完整的 、 正确的系统构件的过程。

在 IEEE 标准 729-1983 中，软件配置管理包括以下几个方面功能：

1.  配置标识：产品的结构 、 产品的构件及其类型，为其分配唯一的标识符，并以某种形式提供对它们的存取。
2.  版本控制：通过建立产品基线，控制软件产品的发布和在整个软件生命周期中对软件产品的修改。例如，它将解决哪些修改会在该产品的最新版本中实现的问题。
3.  状态统计：记录并报告构件和修改请求的状态，并收集关于产品构件的重要统计信息。例如，它将解决修改这个错误会影响多少个文件的问题。
4.  审计和审查：确认产品的完整性并维护构件间的一致性，即确保产品是一个严格定义的构件集合。例如，它将解决目前发布的产品所用的文件的版本是否正确的问题。
5.  生产：对产品的生产进行优化管理。它将解决最新发布的产品应由哪些版本的文件和工具来生成的问题。
6.  过程管理：确保软件组织的规程 、 方针和软件周期得以正确贯彻执行。它将解决要交付给用户的产品是否经过测试和质量检查的问题。
7.  小组协作：控制开发统一产品的多个开发人员之间的协作。例如，它将解决是否所有本地程序员所做的修改都已被加入新版本的产品中的问题。

而在另外一个标准 ISO9000.3 中，对软件配置管理系统做了如下要求：

1.  唯一地标识每个软件项的版本；
2.  标识共同构成一个完整产品的特定版本的每一软件项的版本；
3.  控制由两个或多个独立工作的人员同时对一个给定软件项的更新；
4.  按要求在一个或多个位置对复杂产品的更新进行协调；
5.  标识并跟踪所有的措施和更改；

这些措施和更改是在从开始直到放行期间，由于更改请求或问题引起的。

两个文件都强调了配置管理三个核心部分：版本管理 、 问题跟踪和建立管理，其中版本管理是基础。版本管理应完成以下主要任务：

1.  建立项目；
2.  重构任何修订版的某一项或某一文件；
3.  利用加锁技术防止覆盖；
4.  当增加一个修订版时要求输入变更描述；
5.  提供比较任意两个修订版的使用工具；
6.  采用增量存储方式；
7.  提供对修订版历史和锁定状态的报告功能；
8.  提供归并功能；
9.  允许在任何时候重构任何版本；
10. 权限的设置；
11. 晋升模型的建立；
12. 提供各种报告。

## 2 软件文档管理 ##

所谓文档，是指某种数据媒体和其中所记录的数据。它具有永久性，并可以由人或机器阅读，通常仅用于描述人工可读的东西。在软件工程中，文档常常是用来对活动 、 需求 、 过程或结果进行描述 、 定义 、 规定 、 报告或认证的任何书面或图示的信息。

在软件生产过程中，总是产生和使用大量的信息。软件文档在产品的开发过程中起着重要的作用。

### 2.1 软件文档的作用 ###

**（1）管理依据**

在软件开发过程中，管理者必须了解开发的进度 、 存在的问题和预期目标。每一阶段计划安排的定期报告提供了项目的可见性，把开发过程中发生的事件以某种可阅读的形式记录在文档中。定期报告还提醒各级管理者注意该部门对项目承担的责任及该部门效率的重要性。开发文档规定若干个检查点和进度表，使管理者可以评定项目的进度，如果开发文档有遗漏 、 不完善或内容陈旧，则管理者将失去跟踪和控制项目的重要依据。管理人员可把这些记载下来的材料作为检查软件开发进度和开发质量的依据，分析评估项目 、 检查调整项目 / 计划 、 调配专用资源，实现对软件开发的工程管理。

**（2）任务之间联系的凭证**

大多数软件开发项目通常被划分成若干个任务，并由不同的小组去完成。学科方面的专家建立项目，分析员阐述系统需求，设计员为程序员制定总体设计，程序员编制详细的程序代码，质量保证专家和审查员评价整个系统性能和功能的完整性，负责维护的程序员改进各种操作或增强某些功能。这些人员需要的互相联系是通过文档资料的复制 、 分发和引用而实现的，因而，任务之间的联系是文档的一个重要功能。大多数系统开发方法为任务的联系规定了一些正式文档。分析员向设计员提供正式需求规格说明，设计员向程序员提供正式设计规格说明等

**（3）质量保证**

软件文档能提高开发效率。软件文档的编制使得开发人员对各个阶段的工作都进行周密思考 、 全盘权衡 、 减少返工。并且可在开发早期发现错误和不一致性，便于及时加以纠正。那些负责软件质量保证和评估系统性能的人员需要程序规格说明 、 测试和评估计划 、 测试该系统用的各种质量标准，以及关于期望系统完成什么功能和系统怎样实现这些功能的清晰说明；必须制订测试计划和测试规程，并报告测试结果；他们还必须说明和评估完全控制 、 计算 、 检验例行程序及其他控制技术。这些文档的提供可满足质量，保证人员和审查人员上述工作的需要。

**（4）培训与参考**

软件文档作为开发人员在一定阶段的工作成果和结束标志，它的另一个功能是使系统管理员 、 操作员 、 用户 、 管理者和其他有关人员了解系统如何工作，以及为了达到他们各自的目的，如何使用系统。

**（5）软件维护支持**

记录开发过程中有关信息，便于协调以后的软件开发 、 使用和维护。维护人员需要软件系统的详细说明以帮助他们熟悉系统，找出并修正错误，改进系统以适应用户需求的变化或适应系统环境的变化。软件文档提供对软件的运行 、 维护的有关信息，便于管理人员 、 开发人员 、 操作人员 、 用户之间的协作 、 交流和了解。

**（6）历史档案**

良好的文档系统，作为全组织范围内共享所存储的文档信息，对于软件企业而言，也是一个很好的学习资源。通常文档记载系统的开发历史，可使有关系统结构的基本思想为以后的项目利用。系统开发人员通过审阅以前的系统以查明什么部分已试验过了，什么部分运行得很好，什么部分因某种原因难以运行而被排除。良好的系统文档有助于把程序移植和转移到各种新的系统环境中。

**（7）销售可能**

软件文档便于潜在用户了解软件的功能 、 性能等各项指标，为他们选购符合自己需要的软件提供依据。

从某种意义上来说，良好的文档管理是优秀项目的重要标志，文档是软件开发规范的体现和指南，也是记录和管理知识的重要形式。文档与知识管理文档是固化的知识，是显性知识的重要载体，按规范要求生成一整套文档的过程，就是按照软件开发规范完成一个软件开发的过程。从历史经验来看，写作文档在项目开发的早期可能会使项目的进度比起不写文档要稍慢，但随着项目的进展，部门间配合越来越多 、 开发方对用户需求越来越细，开发者越来越需要知道系统设计的开发思路和用户的进一步功能需求，才能使自己的开发朝着正确的方向推进。一个明显的例子就是系统整合，或者某些环节是建立在其他环节完成的基础之上时，就更显现出文档交流的准确性和高效性。

文档的管理虽然是一个非常烦琐的工作，但是长远来看，它不仅使项目的开发对单个主要人员的依赖减少，从而减少人员流动给项目带来的风险，更重要的是在项目进行到后 10% 的时候起到拉动项目的作用。所以，在使用工程化的原理和方法来指导软件的开发和维护时，应当充分注意软件文档的编制和管理。

### 2.2 文档的归类 ###

按照文档产生和使用的范围，软件文档大致可分为3类：开发文档；管理文档；产品文档。

**（1）开发文档**

开发文档是描述软件开发过程，包括软件需求 、 软件设计 、 软件测试 、 保证软件质量的一类文档，开发文档也包括软件的详细技术描述（程序逻辑 、 程序间相互关系 、 数据格式和存储等）。开发文档起到如下5种作用：

1.  它们是软件开发过程中包含的所有阶段之间的通信工具，它们记录生成软件需求 、 设计 、 编码和测试的详细规定和说明；
2.  它们描述开发小组的职责。通过规定软件 、 主题事项 、 文档编制 、 质量保证人员，以及包含在开发过程中任何其他事项的角色来定义做什么 、 如何做和何时做；
3.  它们用作检验点而允许管理者评定开发进度。如果开发文档丢失 、 不完整或过时，管理者将失去跟踪和控制软件项目的一个重要工具；
4.  它们形成了维护人员所要求的基本的软件支持文档。而这些支持文档可作为产品文档的一部分；
5.  它们记录软件开发的历史。

基本的开发文档包括：

1.  可行性研究和项目任务书；
2.  需求规格说明；
3.  概要设计说明；
4.  详细设计说明，包括程序和数据规格说明；
5.  项目开发计划；
6.  软件集成和测试计划；
7.  质量保证计划 、 标准 、 进度；
8.  安全和测试信息。

**（2）产品文档**

产品文档规定关于软件产品的使用 、 维护 、 增强 、 转换和传输的信息。

产品的文档起到如下 3 种作用：

1.  为使用和运行软件产品的任何人规定培训和参考信息；
2.  使得那些未参加开发本软件的程序员维护它；
3.  促进软件产品的市场流通或提高可接受性。

产品文档主要应用于下列类型的读者：

1.  用户——他们利用软件输入数据、检索信息和解决问题；
2.  运行者——他们在计算机系统上运行软件；
3.  维护人员——他们维护、增强或变更软件。

产品文档包括如下内容：

1.  用于管理者的指南和资料，他们监督软件的使用；
2.  宣传资料通 告软件产品的可用性并详细说明它的功能、运行环境等；
3.  一般信息对任何对其感兴趣的人描 述软件产品。基本的产品文档实物包括：培训手册；
4.  参考手册和用户指南；
5.  软件支持手册；
6.  产品手册和信息广告；
7.  维护修改建议等。

**（3）管理文档**

这种文档建立在项目管理信息的基础上，从管理的角度规定涉及软件生存的信息。它包括：

1.  项目开发计划 、 测试计划；
2.  开发过程的每个阶段的进度和进度变更的记录；
3.  软件变更情况的记录；
4.  相对于开发的判定记录；
5.  开发人员职责定义；
6.  测试报告 、 开发进度月报；
7.  项目开发总结等。

另外，软件文档从用途上还可以分为内部文档和外部文档。

其中，内部文档包括项目开发计划 、 需求分析 、 架构设计说明 、 详细设计说明 、 构件索引 、 构件成分说明 、 构件接口及调用说明 、 构件索引 、 构件接口及调用说明 、 类索引 、 类属性及方法说明 、 测试报告 、 测试统计报告 、 质量监督报告 、 源代码 、 文档分类版本索引和软件安装打包文件等。

外部文档主要包括软件安装手册 、 软件操作手册 、 在线帮助 、 系统性能指标报告和系统操作索引等。

### 2.3 文档编制计划 ###

软件开发的管理部门应该根据本单位承担的应用软件的专业领域和本单位的管理能力，制定一个对文档编制要求的实施规定。对于一个具体的应用软件项目，项目负责人应根据上述实施规定，确定一个文档编制计划。文档计划可以是整个项目计划的一部分或是一个独立的文档。应该编写文档计划并把它分发给全体开发组成员，作为文档重要性的具体依据和管理部门文档工作责任的备忘录。

编制计划的工作应及早开始，对计划的评审应贯穿项目的全过程。如同任何别的计划一样，文档计划指出未来的各项活动，当需要修改时必须加以修改。导致对计划作适当修改的常规评审应作为该项目工作的一部分，所有与该计划有关的人员都应得到文档计划。

文档计划一般包括以下几方面内容：

1.  列出应编制文档的目录；
2.  提示编制文档应参考的标准；
3.  指定文档管理员；
4.  提供编制文档所需要的条件，落实文档编写人员、所需经费及编制工具等；
5.  明确保证文档质量的方法，为了确保文档内容的正确性、合理性，应采取一定的措施，如评 审、鉴定等；
6.  绘制进度表，以图表形式列出在软件生存期各阶段应产生的文档、编制人员、编制日期、完成日期、评审日期等。

还必须明确：

1.  要编制哪几种文档，详细程度如何；
2.  各文档的编制负责人和进度要求；
3.  审 查/批准负责人和时间进度安排；
4.  在开发时期内各文档的维护、修改和管理的负责人，以及 批准手续。

文档计划还应确定该计划和文档的分发，有关的开发人员必须严格执行这个文档 编制计划。文档计划还应该规定每个文档要达到的质量等级，以及为了达到期望的结果必须考虑哪些外部因素。

### 2.4 对文档质量的要求 ###

对文档质量的要求如果不重视文档编写工作，或是对文档编写工作的安排不当，就不可能得到高质量的文档。质量差的文档一般会使读者难以理解，给使用者造成许多不便；会削弱对软件的管理（难以确认和评价开发工作的进展情况），提高软件成本（一些工作可能被迫返工）；造成误操作。一般而言，好的软件文档要求具备如下特征。

**（1）针对性**

文档编制前应分清读者对象。对不同的类型 、 不同层次的读者，决定如何满足适应他们的需要。管理文档主要面向管理人员。用户文档主要面向用户。这两类文档不应像开发文档（面向开发人员）那样过多地使用软件的专业术语。

**（2）精确性**

文档的行文应当十分确切，不能出现多义性的描述。同一课题几个文档的内容应当是协调一致 、 没有矛盾的。

**（3）清晰性**

文档编写应力求简明，如有可能，配以适当的图表，以增强其清晰性。

**（4）完整性**

任何一个文档都应当是完整的 、 独立的，它应自成体系。例如，前言部分应做一般性介绍，正文给出中心内容，必要时还有附录，列出参考资料等。同一课题的几个文档之间可能有部分内容相同，这种重复是必要的。不要在文档中出现转引其他文档内容的情况。如，一些段落没有具体描述，用 “ 见 ×× 文档 ×× 节 ” 的方式。

**（5）灵活性**

各个不同软件项目，其规模和复杂程度有着许多实际差别，不能相同看待。应根据具体的软件开发项目，决定编制的文档种类。

--------------------

![format_png][]

[format_png]: /images/20221124/9c30024db0a14c468da0fa7a4452f739.png