【国家标准】计算机软件文档编制规范20060314

点击蓝字获取更多

计算机软件文档编制规范

Specification for computer software documentation

本标准是GB/T 8567-1988《计算机软件产品开发文件编制指南》的修订版，并改名为《计算机软件文档编制规范》。本标准从实施之日起代替GB/T 8567-1988。

本标准与GB/T 8567-1988相比，主要变化如下：

(a)本标准增加了文档编写过程。其内容参考了ISO/1EC JTC1/SC7 N2106 1999/04/15《软件工程-用户文档过程》。

(b)本标准主要从软件开发与管理的角度，规定相应的文档及规范。其内容依据GB/T 8566-2001《软件生存周期过程》。

(c)在编写本标准时，综合了在软件开发与管理中的经验及中软网络技术股份有限公司有关CMM中拟订的一些文档规范。

(d)本标准与SJ20778-2000《软件开发与文档编制》很好地链接。

(e)本标准在规定软件需求规格说明、软件测试文件、软件质量保证计划与软件配置管理计划等文档时，既依据相应的国标，又根据发展与实践经验作了相应的扩展。

(f)本标准把SJ/T 11291-2003《面向对象的软件系统建模规范 第3部分：文档编制》中的文档编制规范作为本标准的规范性附录。

本标准的附录A是规范性附录。

本标准由中华人民共和国信息产业部提出。

本标准由信息产业部电子工业标准化研究所归口。

本标准起草单位：中软网络技术股份有限公司、信息产业部电子工业标准化研究所、北京联想软件有限公司、用友软件股份有限公司。

本标准主要起草人：周明德、冯惠、韩乃平、欧阳春生、殷树勋、黄万镒、張学锋、韩振江、邓适宜。

1  范围

本标准根据GB/T 8566-2001《信息技术软件生存周期过程》的规定，主要对软件的开发过程和管理过程应编制的主要文档及其编制的内容、格式规定了基本要求。

3.7 构建版；开发阶段build

(1)软件的一个版本，它满足完整的软件所要满足的全部需求的一个特定的子集。

(2)开发满足特定需求子集的软件版本所经历的时间。

注：术语”开发阶段”和”版本”之间的关系依赖于开发方；例如，可以通过几个版本来实现一个开发阶段，一个开发阶段也可以发行几个并行的版本(如发往不同的地点)，或者将它们用作为同义词。

3.8 计算机数据库computerdatabase

见3.14数据库。

3.9 计算机硬件computerhardware

能接收和存储计算机数据的，对计算机数据执行一系列系统性的操作的，或能产生控制输出的设备。这类设备能实现基本的解释、计算、通信、控制或其他逻辑功能。

3.10 计算机程序computerprogram

能使计算机硬件实现计算或控制功能的计算机指令和数据定义的集合。

3.11 计算机软件computer software

见3.32软件。

3.12 计算机软件配置项computer softwareconfigurationitem(CSCI)

满足最终使用功能的软件集合，而且它由需方指定进行单独的配置管理。CSCI应从下列诸因素中进行折衷选择：软件功能、规模、宿主机或目标计算机、开发方、支持概念、重用计划、关键性、接口考虑、是否需要单独编写文档和控制以及其他因素。

3.13 配置项configurationitem

能满足最终使用功能的硬件集合、软件集合或者软、硬件两者的集合，且由需方指定进行单独的配置管理。

3.14 数据库database

以一种能被用户或计算机程序通过一个数据库管理系统进行访问的方式，存储在一个或多个计算机文件中的相关数据的集合。

3.15 数据库管理系统databasemanagementsystem

是一整套计算机程序，它提供为建立、修改、使用和完整性维护一个数据库所需的功能。

3.16 可交付的软件产品deliverable softwareproduct

合同要求交付给需方或其他指定的接受方的软件产品。

3.17 设计design

3.18 开发方developer

开发软件产品的组织(“开发”包括新的软件开发、修改、重用、再工程、维护或产生软件产品的任何其他活动)。开发方可以是一个承制方或者政府机构。

3.19 文档/文档编制document/documentation

能供人或机器阅读的，一般具有永久性的一套资料(不管它们记录在什么媒体上)。

3.20 评价evaluation

确定一个项或一个活动是否满足指定准则的过程。

3.21 固件firmware

硬件设备和以只读软件的形式驻留在硬件设备上的计算机指令和/或计算机数据的组合。

3.22 硬件配置项hardwareconfigurationitem(HWCI)

满足最终使用功能并由需方指定进行单独配置管理的一套硬件。

3.23 独立验证与确认independentverificationandvalidation(IV&V)

由一个机构对软件产品和活动作系统的评估，这个机构不负责该产品的开发或被评估的活动。IV&V不在本标准的范围内。

3.24 接口interface

在软件开发中，两个或多个实体(如CSCI-CSCICSCI-HWCICSCI用户，或软件配置项-软件配置项)之间的关系。这些实体依据这种关系共享、提供或交换数据。接口并不是CSCI、软件配置项或其他的系统部件；接口只是这些实体间的一种关系。

3.25 联合评审jointreview

由需方和开发方双方的代表参加的对项目状态、软件产品和/或项目中的问题进行检查和讨论的活动或会议。

3.26 非交付的软件产品Non-deliverable softwareproduct

不是合同中要求交付给需方或其他指定接受方的软件产品。

3.27 过程process

为实现某个既定目的而进行的一组有组织的活动，例如，软件开发过程。

3.28 合格性测试qualificationtesting

为了向需方表明一个CSCI或系统满足其指定的需求而进行的测试。

3.29 再工程reengineering

为了以一种新的形式重组一个现有的系统而对其进行检查和改造的过程。再工程可包括逆向工程(分析一个系统并产生更高一级的抽象来表示它，如从代码到设计)、重构(在同一个抽象级上把系统从一种表示形式转换到另一种表示形式)、重编文档(分析一个系统并产生用户文档式支持文档)、正向工程(从现有的系统的软件产品结合新的需求，产生新系统)、重定目标系统(对系统进行转换以便将其安装到不同的目标系统上)和翻译(将源码从一种语言转换到另一种语言或者从一种语言的某个版本转换成另一种版本)。

3.30 需求requirement

(1)为了使需方能够接受一个系统或CSCI所必需具备的特性。

(2)本标准或合同中规定的必须遵守的陈述。

3.31 可重用的软件产品reusable softwareproduct

为一个用途开发但还具有别的用途的软件产品，或者专门为了用于多个项目而开发的软件产品，或者在一个项目中有多种作用的软件产品。例子包括(但不限于)上市的商用软件产品，需方已装备的软件产品，重用库中的软件产品和开发方现存的软件产品。每一次使用可以包括这些软件产品的全部或部分，也可以涉及对它的修改。这个术语可以应用于任何软件产品(例如需求，体系结构等)而不只限于软件本身。

3.32 软件software

计算机程序和计算机数据库。

注：虽然有些软件的定义中包括文档，本标准把这个定义只限于计算机程序和计算机数据库。

3.33 软件开发softwaredevelopment

产生软件产品的一整套活动。软件开发可以包括新开发、修改、重用、再工程、维护或者任何会产生软件产品的其他活动。

3.34 软件开发文件softwaredevelopmentfile(SDF)

与特定软件实体开发有关的资料库。其内容一般包括(直接的或引用的)有关需求分忻、设计和实现的考虑、原理和约束条件；开发方内部的测试资料；进度和状态资料。

3.35 软件开发库softwaredevelopmentlibrary(SDL)

一组受控的软件、文档、其他中间的和最终的软件产品，以及相关的用以促进软件的有序开发和后续支持的工具和方法。

3.36 软件开发过程softwaredevelopmentprocess

为了把用户的需求转换成软件产品而进行的一系列有组织的活动。

3.37 软件工程softwareengineering

一般情况下，它是软件开发的同义词。在本标准中，软件工程是软件开发的一个子集,它包含除了合格性测试之外的全部活动。本标准之所以加以这种区分只是为了给软件工程和软件测试环境以不同的命名。

3.38 软件工程环境softwareengineeringenvironment

3.39 软件产品softwareproduct

为了满足一个合同而建立、修改或组合的软件及相关资料。例如包括计划、需求、设计、代码、数据库、测试资料和手册。

3.40 软件质量softwarequality

软件满足所规定的需求的能力。

3.41 软件支持software support

为保证软件安装后能继续按既定目标持续运行而且在系统的运行中能起到既定的作用而实施的一系列活动。软件支持包括软件维护、用户支持和有关的活动。

3.42 软件系统software system

只由软件组成的系统，有时可能还包括该软件赖以运行的计算机设备。

3.43 软件测试环境softwaretestenvironment

为完成软件合格性测试和可能的其他测试所需的设施、硬件、软件、固件、方法和文档。其要素可以包括(但不限于)仿真程序、代码分析程序、测试用例生成程序和路径分析程序，还可能包括在软件工程环境下用到的要素。

3.44 软件移交softwaretransition

使软件开发的责任从一个组织转交给另一个组织的一系列活动。一般说，前一个组织是实现初期软件开发，而后一个组织是进行软件支持。

3.45 软件单元softwareunit

CSCI设计中的一个基本单位：例如，CSCI的一个主要分支，该分支的一个组成部分、一个类、对象、模块、函数、子程序或者数据库。软件配置项可以出现在层次结构的不同层上并可以由其他的软件配置项组成。设计中的软件配置项与实现它们的代码和数据实体(例程、过程、数据库、数据文件等)及或包含这些实体的计算机文件之间不一定有一一对应的关系。

4  缩略语

CASE 计算机辅助软件工程(Computer Assistant Software Engineering)

COM 计算机操作手册(Computer Operation Manual)

CPM 计算机编程手册(Computer Programming Manual)

CSCI 计算机软件配置项(Computer Software Configuration Item)

DBDD 数据库(顶层)设计说明(Database Design Description)

DID 资料条目说明(Data Item Description)

DPMR 开发进度月报(Development Plan Month Report)

DRD 数据需求说明(Data requirement Description)

FAR 可行性分析报告(Feasibility analysis Report)

HWCI 硬件配置项(Hardware Configuration Item)

5.1 概述

有两种主要类型的标准：

(a)产品标准，它规定产品的特征和功能需求；

(b)过程标准，它规定开发产品的过程。

应用程序和计算机软件的复杂性日益增加，使得给使用计算机的用户提供完整的、正确的和易懂的文档的需要更加迫切。本标准通过规定影响软件文档的质量的活动(做什么和由谁做)，提供达到这些目的的工具。

文档常常是关心在软件已经实现后做些什么。然而，为了质量，软件文档编制应作为整个软件生产过程的一部分。过程计划应把文档计划包括在内。本标准也给用户和客户提供工具以保证文档过程实施。

本标准的主要活动是建立开发文档的广泛计划。这是必须的，因为有计划，文档编制的质量会更好，过程的效率会更高。计划必须包括风格规格说明。本标准不规定风格规格说明的内容(即不规定具体的布局和字体)，但它规定风格规格说明必须覆盖什么。本标准也规定何种信息对于文档管理者是可用的和谁做评审和再生产文档。

本标准遵循GB/T 8566-2001《信息技术软件生存周期过程》。为其开发过程和管理过程中的主要文档规定了编制规范。

本标准是按文档由专门的文档管理人员和文本编写人员的模式规定的。 具体的项目可根据具体情况安排。

文档过程的活动应按图1中的顺序执行。

其中，有两个阴影框。在一个阴影框中的所有活动应在下一个阴影框中的活动开始之前完成。在阴影框中的活动可以并行执行。虚线指示可能的重复。

在文档的最小内容已经由需方规定的情况下，这宜由文档管理者在文档计划开发期间纳入。

5.2 源材料准备

需方应允许文档管理者访问以下内容：

(a)所有有关的规格说明、记录格式、屏幕和报告布局、CASE工具输出和文档的准备所需要的任何其他的信息；

(b)若可用，软件的操作副本；

(c)软件的分析员和程序员，以及及时和确切地解答由文档开发人员提出的问题；

(d)若可能，访问典型的用户(为了做读者分析和可用性测试)。

为了增加对产品和它的读者的了解，对软件开发人员的访问是必要的但使这样的访问保持到最小是文档管理者的责任。

不管文档管理者是否是软件的开发者，需方应提供适用的标准、风格和格式指南和其他相关的材料。文档管理者应分发这些材料至需要它的文档开发人员。

保证需方交付给文档管理者的所有材料，当交付时，是完整的和正确的且在交付后保持是最新的，这是需方的责任。

需方保证，提供的材料没有一个违反任何其他部门的知识产权。

文档管理者应采取所有有理由的步骤，以保证由需方提供的材料保持在很好的状态，应保证需方要求的信息安全并在文档项目完成后，所有材料返回给需方。

注：在某些情况下，不是所有材料需要返回；这应在合同中定义。在某 些情况下，由需方传送给文档管理者的材料要求保持机密和安全。合同宜规定对于传送给文档管理者的材料，需方要求文档管理者的机密和安全等级。

5.3 文档计划

5.3.1 概要

文档管理者应准备一份文档计划，此计划规定在文档创建中要执行的工作。此文档计划应经需方正式同意，以预示它完全覆盖了需方的要求。

注：文档计划通常将覆盖整个文档系列。

文档计划应正式地描述计划的文档的范围和限制，以及重要的文档分析和设计决定。也应规定在文档开发期间实现的过程和控制。

文档计划应包括(但不限于)以下内容：

(a)计划的文档的工作名称、目的、范围和限制；

(b)文档的预定的读者，和使用的目的；

(c)文档内容的草案表，带有估计的页数和其他媒体的等效细节；

(d)交付：打印副本数，是否提供电子副本，磁盘和文件格式(包括软件版本)和在何处交付；

(e)版权的拥有者和任何其他所有权；

注：这是复杂的问题，应在合同中规定。

(f)适当处，包括每个文档的安全或机密级；

(g)管理文档开发过程的步骤和控制，包括存储、检索、后备、处理和质量保证(若要求)；

(h)所用的生产方法、工具和工具版本；

(i)文档开发人员所在的队伍的结构，可包括队伍选择计划；

注：在文档编写和生产的不同阶段中的工作人员，需要不同的技巧。编写人员可能要求对正在编写的系统有好的知识加上编写文档的经验；编辑人员可能要求有编辑经验而对系统知识无要求；版面艺术家可能对所用的版面工具外，无任何知识要求。

(j)项目依赖；

(k)所要求的人时和成本；

(l)项目资源需求，包括需方提供的信息和其他资源；

(m)在软件开发期间，软件变更传送信息给文档管理者的方法；

(n)文档的变更控制和维护的计划(任选)；

(o)实现后评审的计划(任选)；

(p)显示适当的里程碑的时间表，包括：

(1)文档计划批准；

(2)每个草案的准备、评审和改正；

(3)可用性测试；

(4)打印、装订和发布。

若适当，这些活动的每一个对于文档的每一项应重复。

注：文档计划宜在文档的开发开始以前准备与批准，以保证所有部门同意目标和所用的方法。批准后，计划宜尽可能广泛地分发；分发宜包括所有文档开发人员和可能包括需方人员及子合同方。

5.3.2 文档计划控制

在正式批准后，文档管理者应控制文档计划和它的发布。文档管理者应保持一份文档计划副本的分发的清单。若以后文档计划变更了(得到文档管理者和需方的同意)，文档管理者应保证所有获得文档计划副本的人员得到变更通知。

注：因为，过时的计划副本可能引起问题，文档管理者宜杜绝计划副本的失控，并制订计划的所有副本已经更新的审核过程。

5.4 文档开发

按文档计划规定进行文档开发。通常，在进行文档开发前，要规定文档的格式(风格)。在软件的开发和管理过程中需要那些文档，每种文档的规范在下面说明。

5.5 评审

5.5.1 概述

本条规定文档评审的要求和相关活动。本条主要以用户文档的评审为例说明。对于开发文档的评审，由供方组织和实施。而批准由开发组织的上级技术机构实施。更要着重经常性的、非正式的注重实效的评审。

用户文档的评审应由需方实现，包括当需要时与文档管理者讨论。

注：评审的目的是保证提交的材料是完整的和正确的并满足了在合同和文档计划中定义的需方的需要。

评审宜由合适的有资格的人员执行，这些人员被授权请求变更和批准文档的内容。

注：需方宜限制评审人员数，满足评审功能所必需的那些即可。

需方在批准每个用户文档草案之前，应保证文档的安全和合法。

为评审交付的文档应包括从文档管理者来的说明书，说明评审的目的和评审员的职责。

注1：在需方和文档管理者之间在整个开发过程期间维持良好的沟通会提高文档的质量并利于评审成功。这宜包括非正式的讨论和尽早地提供样板或初始材料给需方。

注2：在要求的变更超出了合同和文档计划的范围时，需要变更合同。

注3：评审过程不排除文档管理者，他们的责任是试图尽可能保证文档的精确和完整。

注4：宜采用作为评审结果的需方的评论，或在草案上加上标记，或写有适当的参考的评论。需方宜保持变更的副本为了与下一草案相比较。评论应使文档开发人员能实现所要求的变更而不需要评审人员的进一步解释。

注5：对于大的、复杂的系统或正在写文档时系统仍在开发，可能需要多于两次草案和一次校样。在这样情况下，最多的草案数宜在需方和文档管理者之间同意并在文档计划中规定。

5.5.2 文档计划评审

此评审的目的应保证文档计划定义的文档，当完成时，既满足开发过程的需要也满足需方在合同中规定的文档目标。需方同意文档计划，是同意在计划中定义的用户文档的所有可交付的特征。

注：需方宜把注意放在内容的草案表中展示的文档的结构、完整性和可用性。只要适当，文档计划宜在第一个草案开始工作之前评审和批准。

5.5.3 第一个草案评审

第一个草案应包含如在文档计划中描述的文档主体，加上内容表、附录和词汇。在使用自动索引工具处，生成的索引包含位置参照。标点符号、风格和版面应如在文档计划中描述的。

文档的第一个草案的评审目的是核查文档的技术正确性和完整性，以保证草案满足文档计划的目标。标点符号、风格和版面应如在文档计划中定义的。

在批准第一个草案中，除了要求的变更外，要评审批准技术的正确性、结构清楚性和文档的完整性。

注1：第一个草案宜在交付前编辑。这有两个理由：

(a)这保证评审者不分心于改正印刷的和版面的错误；

(b)保证由编辑过程引起的任何技术错误被评审者捕获。

注2：草案应针对在文档计划中批准的目标、读者定义、内容表和其他特征进行评审。在带有评论的第一个草案返回前，宜确认，若草案完全改正了，将满足文档计划的要求。

5.5.4 第二个草案评审

第二个草案应包括在第一个草案评审中同意的所有变更，且应以尽可能接近最后的形式，包括在文档计划中定义的可交付的内容。

此评审的目的是核查在第一个草案中的内容已经正确实现。

在第二个草案的批准中，除了草案的物理形式外，批准文档的所有方面。 草案的物理形式可能与可交付的不精确相同。

注：在批准第二个草案前，宜确认草案(包含评审对草案的评论)已经准备好待批准。

5.5.5 校样评审

校样应包括在第二个草案评审中同意的所有变更。

此评审的目的是核查对第二个草案的评论已正确实现。任何不正确实现的评论应迅速地通知文档管理者，他们应相应地修改文档并返回可替换部分的副本，用于进一步评审。

由批准证明，被接受的文档已准备好生产。

5.6 与其他公司的文档开发子合同

文档管理者应保证子合同的文档遵循本标准，遵循文档计划和合同。

在子合同的文档中，文档管理者作为本标准的“需方”而子合同承担者作为“文档管理者”。

注：文档管理者应与子合同承担者签定符合本标准的协议。

6  文档编制要求

6.1 软件生存周期与各种文档的编制

在软件的生存周期中，一般地说，应该产生以下一些基本文档：

(a)可行性分析(研究)报告；

(b)软件(或项目)开发计划；

(c)软件需求规格说明；

(d)接口需求规格说明；

(e)系统/子系统设计(结构设计)说明；

(f)软件(结构)设计说明；

(g)接口设计说明；

(h)数据库(顶层)设计说明；

(i)(软件)用户手册；

(j)操作手册；

(k)测试计划；

(l)测试报告；

(m)软件配置管理计划；

(n)软件质量保证计划；

(o)开发进度月报；

(p)项目开发总结报告；

(q)软件产品规格说明；

(r)软件版本说明等。

本标准将给出这些文档的编制规范，同时，本标准也是这些文档的编写质量的检验准则。一般地说，一个软件总是一个计算机系统(包括硬件、固件和软件)的组成部分。鉴于计算机系统的多样性，本标准一般不涉及整个系统开发中的文档编制问题，本标准仅仅是软件开发过程中的文档编制指南。

对于面向对象的软件开发，其文档编制要求，参见附录A。

对于使用文档的人员而言，他们所关心的文件的种类随他们所承担的工作而异。

管理人员：可行性分析(研究)报告，项目开发计划，软件配置管理计划，软件质量保证计划，开发进度月报，项目开发总结报告；

开发人员：可行性分析(研究)报告，项目开发计划，软件需求规格说明，接口需求规格说明，软件(结构)设计说明，接口设计说明书，数据库(顶层)设计说明，测试计划，测试报告；

维护人员：软件需求规格说明，接口需求规格说明，软件(结构)设计说明，测试报告；

用户：软件产品规格说明，软件版本说明，用户手册，操作手册。

本标准规定了在软件开发过程中文档编制的要求，这些文档从使用的角度可分为用户文档和开发文档两大类。其中，用户文档必须交给用户。用户应该得到的文档的种类和规模由供应者与用户之间签订的合同规定。

如前所述，软件，从出现一个构思之日起，经过软件开发成功投入使用，直到最后决定停止使用并被另一项软件代替之时止，被认为是该软件的一个生存周期，一般地说这个软件生存周期可以分成以下6个阶段：

(a)可行性与计划研究阶段；

(b)需求分析阶段；

(c)设计阶段；

(d)实现阶段；

(e)测试阶段；

(f)运行与维护阶段。

在可行性分析(研究)与计划阶段内，要确定该软件的开发目标和总的要求，要进行可行性分析、投资一收益分析、制订开发计划，并完成可行性分析报告、开发计划等文档。

在需求分析阶段内，由系统分析人员对被设计的系统进行系统分析，确定对该软件的各项功能、性能需求和设计约束，确定对文档编制的要求，作为本阶段工作的结果，一般地说软件需求规格说明(也称为：软件需求说明、软件规格说明)、数据要求说明和初步的用户手册应该编写出来。

在设计阶段内，系统设计人员和程序设计人员应该在反复理解软件需求的基础上,提出多个设计，分析每个设计能履行的功能并进行相互比较，最后确定一个设计，包括该软件的结构、模块(或CSCI)的划分、功能的分配,以及处理流程。在被设计系统比较复杂的情况下，设计阶段应分解成概要设计阶段和详细设计阶段两个步骤。在一般情况下，应完成的文档包括：结构设计说明、详细设计说明和测试计划初稿。

在实现阶段内，要完成源程序的编码、编译(或汇编)和排错调试得到无语法错的程序清单，要开始编写进度日报、周报和月报(是否要有日报或周报，取决于项目的重要性和规模)，并且要完成用户手册、操作手册等面向用户的文档的编写工作，还要完成测试计划的编制。

在测试阶段：该程序将被全面地测试，已编制的文档将被检查审阅。一般要完成测试分析报告。作为开发工作的结束，所生产的程序、文档以及开发工作本身将逐项被评价，最后写出项目开发总结报告。

在整个开发过程中(即前五个阶段中)，开发集体要按月编写开发进度月报。

在运行和维护阶段，软件将在运行使用中不断地被维护，根据新提出的需求进行必要而且可能的扩充和删改、更新和升级。

6.2 文档编制中的考虑因素

文档编制是开发过程的有机组成部分，也是一个不断努力的工作过程。 是一个从形成最初轮廓、经反复检查和修改，直至程序和文档正式交付使用的完整过程。其中每一步都要求工作人员做出很大努力。要保证文档编制的质量，要体现每个开发项目的特点，也要注意不要花太多的人力。 为此编制中要考虑如下各项因素。

6.2.1 文档的读者

每一种文档都具有特定的读者。这些读者包括个人或小组、软件开发单位的成员或社会上的公众、从事软件工作的技术人员、管理人员或领导干部。他们期待着使用这些文档的内容来进行工作，例如设计、编写程序、测试、使用、维护或进行计划管理。因此这些文档的作者必须了解自己的读者。这些文档的编写必须注意适应自己的特定读者的水平、特点和要求。

6.2.2 重复性

本标准中列出的文档编制规范的内容要求中，显然存在某些重复。较明显的重复有两类。引言是每一种文档都要包含的内容，以向读者提供总的梗概。第二类明显的重复是各种文档中的说明部分，如对功能性能的说明；对输入、输出的描述；系统中包含的设备等。这是为了方便每种文档各自的读者，每种文档应该自成体系，尽量避免读一种文档时又不得不去参考另一种文档。当然,在每一种文档里，有关引言、说明等同其他文档相重复的部分，在行文上、在所用的术语上、在详细的程度上，还是应该有 一些差别以适应各种文档的不同读者的需要。

6.2.3 灵活性

鉴于软件开发是具有创造性的脑力劳动，也鉴于不同软件在规模上和复杂程度上差别极大，在文档编制工作中允许一定的灵活性。这种灵活性如下所述。

(a)应编制的文档种类

尽管本标准认为在一般情况下，一项软件的开发过程中，应产生如上所述的各种文档，然而针对一项具体的软件开发项目，有时不必编制这么多的文档，可以把几种文档合并成一种。一般地说，当项目的规模、复杂性和失败风险增大时，文档编制的范围，管理手续和详细程度将随之增加，反之，则可适当减少。为了恰当地掌握这种灵活性，本标准要求贯彻分工负责的原则，这意味着：

(1)一个软件开发单位的领导机构应该根据本单位经营承包的应用软件的专业领域和本单位的管理能力，制定一个对文档编制要求的实施规定，主要是：在不同的条件下，应该形成哪些文档？这些文档的详细程度？该开发单位的每一个项目负责人，必须认真执行这个实施规定。

(2)对于一个具体的应用软件项目，项目负责人应根据上述实施规定，确定一个文档编制计划(可以包含在软件开发计划中)，其中包括：

1应该编制哪几种文档，详细程度如何？

2各个文档的编制负责人和进度要求；

3审查、批准的负责人和时间进度安排；

4在开发时间内，各文档的维护、修改和管理的负责人，以及批准手续。

每项工作必须落实到人。这个文件编制计划是整个开发计划的重要组成部分。

(3)有关的设计人员则必须严格执行这个文档编制计划。

(b)文档的详细程度

从同一份提纲起草的文件的篇幅大小往往不同，可以少到几页,也可以长达几百页。对于这种差别，本标准是允许的。此详细程度取决于任务的规模、复杂性和项目负责人对该软件的开发过程及运行环境所需要的详细程度的判断。

(c)文档的扩展

当被开发系统的规模非常大〈例如源码超过一百万行〉时，一种文档可以分成几卷编写，可以按其中每一个系统分别编制；也可以按内容划分成多卷，例如：

项目开发计划可能包括：质量保证计划，配置管理计划，用户培训计划，安装实施计划；

系统设计说明可分写成：系统设计说明，子系统设计说明；

程序设计说明可分写成：程序设计说明，接口设计说明，版本说明；

操作手册可分写成：操作手册，安装实施过程；

测试计划可分写成：测试计划，测试设计说明，测试规程，测试用例；

测试分析报告可分写成：综合测试报告，验收测试报告；

项目开发总结报告，亦可分写成项目开发总结报告和资源环境统计。

(d)章、条的扩张与缩并

在软件文档中，一般宜使用本标准提供的章、条标题。但所有的条都可以扩展，可以进一步细分，以适应实际需要。反之如果章条中的有些细节并非必需，也可以根据实际情况缩并。此时章条的编号应相应地变更。

(e)程序设计的表现形式

本标准对于程序的设计表现形式并未作出规定或限制，可以使用流程图的形式，判定表的形式，也可以使用其他表现形式，如程序设计语言(PDL)、问题分析图(PALb)等。

(f)文档的表现形式

本标准对于文档的表现形式亦未作出规定或限制。可以使用自然语言，也可以使用形式化语言。也可以使用各种图、表。

(g)文档的其他种类

当本标准中规定的文档种类尚不能满足某些应用部门的特殊需要时，他们可以建立一些特殊的文档种类要求，例如软件质量保证计划、软件配置管理计划等，这些要求可以包含在本单位的文件编制实施规定中。

7  文档编制格式

7.1 可行性分析(研究)报告(FAR)

附录A

(规范性附录)

面向对象软件的文档编制

A.1 综述

在一个面向对象的软件系统建模中，一般地说，应产生下列文档：

总体说明文档；

用况图文档；

类图文档；

顺序图文档；

协作图文档；

状态图文档；

活动图文档；

构件图文档；

部署图文档；

其中有的文档有时会引入包图来管理信息组织的复杂性。

开发者也可根据所承担项目的实际情况，灵活取舍或增补。

当开发者强调过程控制时，也可以形成需求定义文档、分析文档和设计文档等。

其中每种文档的内容包含一个或多个上面提到的各种图文档。

A.2 总体说明文档

以文本方式，对整个系统作一些必要的说明。内容包括系统的目标、意义、应用范围、项目背景和文档组成等。但不必对系统的总体进行详细地说明，只需作提纲掣领式的简单介绍。另外，还要说明系统的建模文档由哪几种具体的文档组成、每种文档的份数以及对各种文档的组织等。

A.3 用况图文档

A.3.1 图形文档

即所绘制的用况图。

A.3.2 文字说明

用况图文档由以下部分组成：用况图综述、参与者描述、用况描述、用况图中元素间的关系描述和其他与用况图有关的说明。

A.3.2.1 用况图综述

从总体上阐述整个用况图的目的、结构、功能以及组织。以文字描述文档所包含的部分。

A.3.2.2 参与者描述

列出一个用况图中的每个参与者的名称，可按字母顺序或其他某种有规律的次序排列。必要时要对参与者附有必要的文字说明，也可以说明它所涉及到的用况和交互图的名称。

A.3.2.3 用况描述

对于一个用况图中的每个用况，记录如下的信息。要按某种顺序排列它们。

(a)名称

每个用况有一个在图内唯一的名字，并且该名字要反映出它所描述的功能。书写位置是在用况描述的第一行。

(b)行为描述

用自然语言分别描述参与者的行为和系统行为，建议把参与者的行为靠左对齐书写，把系统行为靠较右的位置对齐书写。

在描述较复杂的含有循环或条件分支的行为时，可使用一些结构化编程语言的控制语句，如”while，for，if-then-else等。

当要表明控制语句的作用范围时，可使用括号，如{、}或begin、end 等，也可以使用标号，以便更清楚地表示控制走向。

如有必要，可使用顺序图、状态图或协作图描述参与者的行为和系统行为。

(c)用况图中元素间的关系描述

产生一份描述用况图中的参与者与用况间、用况间以及参与者间关系的文字性描述文档。具体地由下面几部分构成：

1关系的名称；

2关系的类型：关联，泛化，包含，扩展；

3关系所涉及的类目：对关系所连接的类目应指明名称和类型(参与者或用况)。

(d)其他与用况图有关的说明

与该用况图有关的但上面文档中没有涉及的其他信息的描述。

A.4 类图文档

A.4.1 图形文档

即所绘制的类图。

A.4.2 文字说明

文字描述由以下部分组成：类图综述、类描述、关联描述、泛化描述、依赖描述和其他与类图有关的说明。在实际使用时，这些部分是可选的。

A.4.2.1 类图综述

从总体上阐述整个类图的目的、结构、功能及组织。以文字描述文档所包含的部分。

A.4.2.2 类描述

类描述包括类整体说明、属性说明、服务说明、关联说明、泛化说明、依赖说明及其他说明。

(a)类的整体说明

对整个类及其对象的情况加以说明，内容包括：

1类名：应是中文名或英文名；

2解释：对类的责任的文字描述；

3一般类：描述该类是从那些类泛化而来的；

4状态转换图：描述该类的实例的状态图的名称列表；

5主动性：有无主动性；

6永久性：有无永久性；

7引用情况：若此类为其他类图所定义，则要标明它所属于的类图；若此类被其他类图引用，则标明所引用的类图；

8多重性；

9其他：是否有特别的数据完整性或安全性要求等。

(b)属性说明

逐个地说明类的属性。每个属性的详细说明包括以下内容：

1属性名：中文属性名或英文属性名；

2多重性：该属性的多重性；

3解释：该属性的作用；

4数据类型；

5聚合关系：如果这个属性的作用是为了表明聚合关系，则在这里说明这种关系；

6组合关系：如果这个属性的作用是为了表明组合关系，则在这里说明这种关系；

7关联关系：如果这个属性是为了实现该类的对象和其他对象之间的链而设置的，则在这里明确地说明这一点；

8实现要求：该属性的取值范围、精度、初始值及其他描述。

(c)服务说明

逐个地说明类中的每个服务。每个服务的详细说明包括以下内容：

1服务名：中文服务名或英文服务名；

2主动性：有无主动性；

3多态性：有无多态性；

4解释：该服务的作用；

5服务的活动图：详细描述活动具体细节的活动图的名称列表；

6约束条件及其他：若该服务的执行有前置条件、后置条件或执行时间的要求等其他需要说明的事项，则在此说明。

(d)关联

描述该类所涉及的所有的关联。每个与该类相关的关联可有关联名。

(e)泛化

描述该类所涉及的所有的泛化。每个与该类相关的关联可有泛化名。

(f)依赖

描述该类所涉及的所有依赖。每个与该类相关的依赖可有依赖名。

A.4.2.3 关联描述

类图中的每一关联都应有如下的描述：

(a)关联名称：中文关联名或英文关联名；

(b)关联的类型：应是一般二元关联、聚合、组合、多元关联、自关联、限定关联、导出关联、其他关联；

(c)关联所连接的类：按照一定顺序列举出关联所连接的类；

(d)关联端点:对每一个关联端点描述如下：

1导航性：是否有导航性；

2排序：是否排序；

3聚合：是否有聚合，如果有，则要指明是聚合还是组合；

4多重性；

5可变性：应是无、只增加、冻结；

6角色：角色名用中文名和英文名表示均可；

7可见性：用+、一、#表示；

8接口说明符。

A.4.2.4 泛化描述

类图中的每一个泛化都有如下的描述：

(a)泛化关系中的父类；

(b)泛化关系中的子类；

(c)泛化关系中的区分器；

(d)泛化关系中的限制符：应是完全、不完全、重叠和不相交。

A.4.2.5 依赖描述

类图中的每一个依赖都有如下的描述：

(a)依赖名称；

(b)依赖所涉及的类的名称；

(c)依赖的类型；

(d)依赖的附加说明。

A.4.2.6 其他描述文档

与该类图有关的但上面文档中没有涉及的其他信息的描述。

A.5 顺序图文档

A.5.1 图形文档

即所绘制的顺序图。

A.5.2 文字说明

顺序图的文字说明文档应包含：顺序图综述、顺序图中的对象与参与者描述、对象接收/发送信息的描述和其他与顺序图有关的说明。

A.5.2.1 顺序图综述

从总体上描述该顺序图的目的，以及所涉及的对象和参与者。

A.5.2.2 顺序图中的对象与参与者描述

对顺序图中的所有的对象和参与者依次进行如下的描述：

(a)对象类型：是参与者还是类；

(b)对象名称；

(c)是否为主动对象：是或否，此描述针对对象而言，对于参与者不应有此描述；

(d)其他与对象或参与者有关的信息。

A.5.2.3 对象接收发送消息的描述

对顺序图中的每一个对象或参与者，详细地描述其接收/发送消息的类型、时序及与其他消息之间的触发关系。对每一个对象和参与者应按照时间顺序分别列出该对象或参与者所接收/发送的全部消息。对每一条消息应包含下面的内容：

(a)消息名称；

(b)是发送消息还是接受消息；

(c)消息类型；

(d)若为接收消息，应列出该消息所直接触发的消息的名称列表；

(e)是否为自接收消息；

(f)消息的发送对象名称；

(g)消息的接收对象名称。

A.5.2.4 其他与顺序图有关的说明

与顺序图有关的补充信息。

A.6 协作图文档

A.6.1 图形文档

即所绘制的协作图。

A.6.2 文字说明

协作图的文字说明应包含下列部分：协作图综述、协作图中的对象或角色描述、对象或角色接收/发送消息的描述、对象或角色间的链描述和其他与协作图有关的说明。

A.6.2.1 协作图综述

从总体上描述该协作图的目的以及其所涉及的对象或类元角色。

A.6.2.2 协作图中的对象或角色描述

对协作图中的所有类元角色或对象，依次列出下面的各项：

(a)名称；

(b)类型：类元角色或对象；

(c)是否为主动对象或角色：是或否；

(d)其他与类元对象有关的信息。

A.6.2.3 对象或角色接收/发送消息的描述

对协作图中的每一个类目角色或实例，详细地描述其接收/发送消息的类型及时序，以及与其他消息的触发关系。每一类目角色或实例应有下列描述：

(a)对象或角色名称；

(b)列出该对象所接收/发送的全部消息流，对每一条消息应包含下面的信息：

1消息名称；

2消息的格式：参见概念和表示法部分；

3是发送消息还是接收消息；

4消息类型；

5若为接收消息应列出该消息所直接触发的消息序列；

6是否为自接收消息；

7消息的发送类目角色或实例；

8消息的接收类目角色或实例。

A.6.2.4 对象或角色间的链描述

对象间或角色间的链应由下面的成分构成：

(a)链名称；

(b)链所连接的角色或对象的名称；

(c)链上的角色名，每个角色应包含下列信息：

1角色名：中文名或英文名；

2可见性：+丶一或#；

3特殊的衍型：Global、Local、Parameter、Self、Vote、Broadcast；

(d)其他与链有关的信息。

A.6.2.5 其他与协作图有关的说明

与协作图有关的补充信息。

A.7 状态图文档

A.7.1 图形文档

即所绘制的状态图。

A.7.2 文字说明

状态图的文字说明应包含：状态图综述、状态图的状态描述、状态图的转换描述和其他与状态图有关的说明。

A.7.2.1 状态图综述

从总体上，该状态图描述一个对象在外部激励的作用下进行的状态变迁、所涉及到的状态和转换以及设置该状态图的目的等。

A.7.2.2 状态图的状态描述

描述一个状态图的所有的状态，对每一个具体状态应包括以下各项：

(a)状态的名称：中文名或英文名；

(b)状态的类型：简单状态，并发组合状态，顺序组合状态，子状态，初 始伪状态，终状态，结合状态，历史状态，引用状态，桩状态，同步状态；

(c)入口动作；

(d)出口动作；

(e)内部转换：由一系列的内部转换项组成。每个内部转换项有下列格式：

动作标号/动作表达式；

(f)若为组合状态应列举出其所包含的子状态；

(g)其他与该状态有关的信息。

A.7.2.3 状态图的转换描述

本文档用来描述一个状态图的所有的状态转换，每一个具体转换应包括以下各项：

(a)转换的源状态；

(b)转换的目标状态；

(c)转换串：事件特征标记[9监护条件‘]9‘/9动作表达式；

(d)转换中的分支：同步条、结合点、动态选择点。

A.7.2.4 其他与状态图有关的说明

与状态图有关的补充信息。

A.8 活动图文档

A.8.1 图形文档

即所绘制的活动图。

A.8.2 文字说明

活动图的文字说明包含：活动图综述、活动图中的动作状态描述、活动图中的转换描述和其他与活动图有关的说明。

A.8.2.1 活动图综述

从总体上，活动图描述一个对象的一个操作的活动序列，或者是多个对象为完成某一目的而进行的协作所涉及的活动序列，以及设置该活动图的目的等。若活动图用于描述系统的其他目的，也按本格式描述。

A.8.2.2 活动图中的动作状态描述

本文档用来描述一个活动图的所有的动作状态，每个具体动作状态包括以下内容：

(a)名称：中文名或英文名；

(b)类型：一般动作状，子动作状态，信号发送，信号接收，初始伪动作状态，终动作状态，历史状态；

(c)入口转换；

(d)出口转换；

(e)活动伪码；

(f)其他与该状态有关的信息。

A.8.2.3 活动图中的转换描述

本文档用来描述一个活动图的所有的转换，每一个具体转换包括以下内容：

(a)转换的名称；

(b)源动作状态；

(c)终动作状态；

(d)转换中的分支：包括分叉、同步条、决策和合并；

(e)转换中的控制分叉：包括控制分叉的名称、与分叉相连的入口和出口元素的名称。

A.8.2.4 其他与状态图有关的说明

与状态图有关的补充信息，如泳道的划分、对象流、信号发送和信号接收等信息。

A.9 构件图文档

A.9.1 图形文档

即所绘制的构件图。

A.9.2 文字说明

构件图的文字说明文档包含：构件图综述、构件图中的构件描述、构件图中的关系描述和其他与构件图有关的说明。

A.9.2.1 构件图的综述

从总体上，构件图描述构件间的依赖关系、设置该构件图的目的等。

A.9.2.2 构件图中的构件描述

构件图中的每一个构件包含下列描述：

(a)构件名称；

(b)构件的接口；

(c)构件所涉及的关系；

(d)在逻辑上构件所实现的类；

(e)构件的类型。

A.9.2.3 构件图中的关系描述

(a)关系的名称；

(b)关系的起始构件的名称；

(c)关系的结束构件的名称；

(d)关系的类型：实现依赖、使用依赖或其他依赖。

A.9.2.4 其他与构件图有关的说明

其他与构件图有关的信息。

A.10 部署图文档

A.10.1 图形文档

即所绘制的部署图。

A.10.2 文字说明

部署图的文字说明文档包含：部署图综述、部署图中的节点描述、部署图中的关系描述和其他与部署图有关的说明。

A.10.2.1 部署图综述

从总体上描述部署图的目的以及节点之间的相互关系等。

A.10.2.2 部署图中的节点描述

对部署图中的每一个节点包含下列描述：

(a)节点名称；

(b)节点中的构件实例；

(c)节点所涉及的链的名称；

(d)节点的类型。

A.10.2.3 部署图中的关系描述

(a)关系的名称；

(b)关系的起始节点(或构件)的名称；

(c)关系的结束节点(或构件)的名称；

(d)关系的类型：实现依赖、使用依赖、其他依赖或通讯链。

A.10.2.4 其他与部署图有关的说明

其他与部署图有关的信息。

A.11 包图文档

为了管理模型的信息组织的复杂性，在比较复杂的模型中，通常将关系联系比较密切的图形元素划分到一个包里面。

A.11.1 图形文档

即所绘制的包图。

A.11.2 文字说明

包图的文字说明文档包含：包图的综述、包图中的包描述和其他与包图有关的说明。

A.11.2.1 包图的综述

从总体上描述包图的名称、目的以及与其他包的相互关系等。

A.11.2.2 包图中的包描述

包图中的每一个包包含下列描述：

(a)包的名称；

(b)包的种类：类包、用况包或其他；

(c)详细描述该包所包含的建模元素所在的文档；

(d)与该包有关系的其他包’应包括如下信息：

1包的名称；

2与该包的关系：依赖(访问和移入)、泛化’要注明方向性。

A.11.2.3 其他与包图有关的说明

其他与包图有关的信息。

参考文献

GB 9385-1988《计算机软件需求规格说明编制指南》。

GB 9386-1988《计算机软件测试文件编制规范》。

GB/T 12504-1990《计算机软件质量保证计划规范》。

GB/T 12505-1990《计算机软件配置管理计划规范》。

SJ/T 11291-2003《面向对象的软件系统建模规范 第3部分：文档编制》。

SJ 20778-2000《软件开发与文档编制》。

ISO/IEC JTC1/SC7 N2106 1999/04/15《软件工程-用户文档过程》

ICCD

扫码关注“并刃汇咨询发展”

点分享

点点赞

点在看