软件开发文档规范

单击以编辑,母版标题样式,单击以编辑母版文本样式,第二级,第三级,第四级,第五级,*,软件开发文档规范,工程软件专家组,何新贵,2001年8月,前言,本标准与,GJB 2786-96,软件开发,配套使用。,工程“白皮书”综合了,GJB 2786-96、GJB 438A-97,和,GJB/Z 115-98。,本标准允许根据实际情况进行剪裁，以适应实际需要。,1. 范围,1.1 主题内容,规定应用软件开发文档编制的格式、内容和要求。,1.2 适用范围,适用计算机软件开发过程中的文档编制，特别适用于同,GJB 2786-96,配套使用。,2. 引用文件（略）3. 定义（略）4. 一般要求,4.1 文档种类（一）,系统和段设计文件 软件开发计划,软件需求规格说明 接口需求规格说明,接口设计文档 软件设计文档,软件产品规格说明 版本说明文档,4.1 文档种类（二）,软件测试计划 软件测试说明,软件测试报告 计算机系统操作员手册,软件用户手册 软件程序员手册,固件保障手 计算机资源综合保障手册,数据库设计,4. 一般要求（一）,4.2 文档的产生,根据,GJB 2786-96,中各阶段描述的工作任务而产生相应的文档。详见,GJB 2786-96。,4. 一般要求（二）,4.3,文档的准备 * 可用书面形式或电子多媒体形式 * 剪裁说明：种类和内容都可剪裁，内容可用 “本节无内容”方式剪裁，以便保留章节号。 * 页码编制：参见文档模板。 * 文档控制号：按标准编制或自定义。 * 自变量：例如3.2.,x,实际可为3.2.1、3.2.2、.,4. 一般要求（三）,4.4 文档的结构,软件文档由封面、目录、正文、注释和附录组成。,详见标准。,5 详细要求,*,详细要求将对16个软件文档分别叙述,其格式、内容和要求。,* 每个文档分为目录和正文两部分。,5.1 系统和段设计文件,1 此为一个系统设计文件，描述：系统任务、运行环境、支持环境、系统体系结构、运行情况、系统设计、处理资源、质量因素以及需求的可追踪性等内容；,2 系统设计把系统的任务分配给硬件、软件和手工操作，并确定其间的内部接口；,3 由此派生出对软件的要求，故它是进行软件需求分析的基础。,5.2 软件开发计划（一）,1 要求按,GJB 2786-96,软件开发的一般要求中叙述的五项职能：,* 软件开发管理；,* 软件工程；,* 正式合格性测试；,* 软件产品评价；,* 软件配置管理；以及,* 其它软件开发职能,六个方面来制定软件开发计划。,5.2 软件开发计划（二）,2 所有软件开发工作都应按“软件开发计划”的规定进行，若要修改，必须经过严格的批准手续。,* 不但要详细叙述本项目的开发计划，而且要,概述与其它有关项目（包括硬件、软件）开,发计划的关系，以便协同工作。,5.2 软件开发计划（三）,* 由于我国国情，开发计划中有些条目可能编,写比较困难，但为了按时保质保量地完成任,务，应尽量编制好软件开发计划，并严格执,行它。,5.2 软件开发计划（四）,3 软件开发管理描述：,* 项目的组织机构和资源；,* 进度和里程碑；,* 风险管理；,* 安全保密；,* 与其它承制方的关系和接口；,* 与其它,IV&V,机构的关系和接口；,5.2 软件开发计划（五）,3 软件开发管理描述：,* 转承制方的管理；,* 正式审查；,* 软件开发库管理；,* 问题纠正过程管理；,* 问题/更改报告。,5.2 软件开发计划（六）,4 软件工程描述：,* 开发组织机构和资源；,* 软件标准和研制程序；,* 非开发软件的获取和使用；,5 正式合格性测试描述：,* 测试组织机构和资源；,* 测试方法和基本原理；,* 测试计划的假设条件和约束。,5.2 软件开发计划（七）,6 软件产品评价：,* 评价组织机构和资源；,* 软件产品评价的规程工具；,* 转承制方的产品；,* 软件产品评价记录的格式、内容等；,* 分节描述每个软件开发产品在各开发阶段的产品评价计划、评价标准（若需修改,GJB 2786,规定的评价标准的话,）等；,5.2 软件开发计划（八）,7 软件配置管理：,* 管理组织机构和资源；,* 配置标识；,* 配置控制；,* 配置状况报告；,* 配置审核；,* 让签约机构认可规格说明的准备工作；,* 配置管理的主要里程碑。,5.2 软件开发计划（九）,8 其它软件开发职能,分节描述各个开发职能：,8.,x,职能名,8.,x.1,组织机构职能名,8.,x.2,其它资源职能名,8.,x.3,方法和规程职能名,5.3 软件需求规格说明（一）,1 软件需求规格说明是需求分析的产物，是一项重要的软件开发产品。,2 软件需求规格说明分为：,* 工程需求；,* 合格性需求；,* 交付准备；,三方面来描述。,5.3 软件需求规格说明（二）,3 工程需求,工程需求要求描述：,*,CSCI,的外部接口需求；,*,CSCI,的功能需求（按功能分节叙述）；,*,CSCI,的内部接口；,*,CSCI,的数据元素要求；,* 适应性需求；,* 容量和时间要求；,5.3 软件需求规格说明（三）,工程需求要求描述：,*,安全,要求；,*,保密,要求；,*,设计约束,；,*,软件,质量因素；,* 人的特性/人的工程需求；,* 需求可追踪性。,5.3 软件需求规格说明（四）,4 合格性需求,合格性需求分节证明软件合格的方法和,级别和特殊的合格性需求：,4.1 合格性方法和级别,4.2 特殊合格性需求,5 交付准备,说明：,CSCI,介质的类型和特性；,介质的标签、包装、处置和分类；,其它特殊的交付要求。,5.4 接口需求规格说明（一）,1 本文档将描述,CSCI,的各个外部接口的需求。,2 当外部接口不多，也不复杂时，也可把此文档合并到软件需求规格说明。,5.4 接口需求规格说明（二）,3 接口说明,3,.,1 接口示意图,3.,x,接口名,分节描述该接口：,3.,x.1,接口需求,包括说明：并发,/,顺序执行；通信协议；,优先级。,5.4 接口需求规格说明（三）,3 接口说明,3,.,1 接口示意图,3.,x,接口名,分节描述该接口：,3.,x.2,数据要求,详细说明跨接口数据的来源、目的、度量单位、值域、精度和分辨率等,。,5.5 接口设计文档（一）,1 本文档将描述,CSCI,的各个外部接口的设计。,2 当外部接口不多，也不复杂时，也可把此文档合并到软件设计文档。,5.5 接口设计文档（二）,3 接口设计,3,.,1 接口示意图,3.,x,接口名,分节描述该接口的设计：,3.,x.1,数据元素,在数据元素定义表中对跨接口数据元素详细提供来源、目的、度量单位、值域、精度和分辨率、数据类型、表示格式、优先级等信息,。,5.5 接口设计文档（三）,3.,x.2,消息描述,标识接口间的每个消息，并描述数据元素对消息的功用。,3.,x.3,接口优先级,规定消息通过该接口的相对优先级次序。,3.,x.4,通信协议,分节描述与该接口相连的通信协议。,5.6 软件设计文档（一）,1 本文档将描述,CSCI,的概要设计和详细设计。,2 当,CSCI,较复杂时，也可把此文档分为软件概要设计文档和软件详细设计文档。,5.6 软件设计文档（二）,3 概要设计,描述,CSCI,的概要设计。,3,.,1,CSCI,概述,3.1.1,CSCI,结构,用结构图描述,CSCI,的结构和外部接口。,3.1.2 系统状态和模式,除系统状态和模式外，还应描述相应的控制流和数据流。,3.1.3 内存和进程时间分配,5.6 软件设计文档（三）,3.2,CSCI,设计说明,分节说明其每个,CSC,的设计说明。,3,.2.,x CSC,名及标识号,利用下层,CSC,间的,控制流和数据流描述该,CSC,的概要设计，也可用其它描述方式。,3.2.,x.y,下一层,CSC,名及标识号,往下逐层描述,CSC,的概要设计。,复杂的,CSCI,可能有多层,CSC。,5.6 软件设计文档（四）,4 详细设计,分节描述,CSCI,中每个,CSC,的详细设计。,4,.,x CSC,名及标识号,用其,CSU,间的控制流和数据流描述,CSU,间关系，描述,CSC,的外部接口，并,分小节逐个描述其中的每个,CSU。,4.x.y CSU,名及标识号,描述功能，并分下列小小节描述,各种设计信息。,5.6 软件设计文档（五）,4.,x.y.1 (CSU,名)的设计需求及约束,描述该,CSU,的设计需求及约束。,4.,x.y.2 (CSU,名)的设计,用流程图、,PDL,等设计工具描述该,CSU,的详细设计信息（详见标准）。,5,CSCI,数据,描述,CSCI,的所有全局数据元素和外部接口数据元素。,5.6 软件设计文档（六）,6,CSCI,数据文件,分节描述,CSCI,的每个共享数据文件。,6,.,1,CSC/CSU,数据文件交叉引用,为,CSC/CSU,使用下列数据文件提供一张引用表。,5.6 软件设计文档（七）,6.2 描述信息,6.2.,x,数据文件名及标识号,陈述数据文件的用途、大小、存取方法、记录结构和大小、数据表示、类型、单位、值域、精度和分辨率等。,7 需求的可追踪性,用图表表示各个,CSU,一直到规格说明中的需求。每个需求都需有相应的,CSU,来实现。,5.7 软件产品规格说明（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,5.7 软件产品规格说明（二）,3 要求,3.1 软件设计,写出或引用软件设计文档。,3.2,CSCI,源代码列表,列出或引用源代码列表，并给出其中 每个,CSC,和,CSU,在列表中位置的索引。,3,.,3 编译程序/汇编程序,列出所用的编译程序/汇编程序。,3.3 测量资源,5.8 版本说明文档（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,3 版本说明,3.1 发放的材料清单,物理介质和新版本的文档。它是操作、装入或生成,CSCI,的依据。,5.8 版本说明文档（二）,3.2,CSCI,内容清单,软件清单和说明。,3.3 更改安装,从上一版以来的所有更改清单和影响索引。,3.4 修改数据,初始版本的特殊数据和修改情况。,5.8 版本说明文档（三）,3.5 接口兼容性,陈述更改对系统和配置项接口的影响。,3.6 引用文档摘要,列出所有与初始版本有关的文档。,3.7 更改总结,总结3.3所述每个更改的影响。,3.8 安装说明,3.9 可能的问题和已知的错误,5.9 软件测试计划（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,1.4 与其它计划的关系,2 引用文档,5.9 软件测试计划（二）,3 软件测试环境,3.1 软件项,操作系统、编译程序测试工具。,3.2 硬件和固件项,3.3 权限,测试环境有关的专利和使用权限。,3.4 安装、测试与控制,安装、测试与控制软件测试环境的计划。,5.9 软件测试计划（三）,4 正式合格性测试,4.,X （CSCI,名称和项目唯一标识号,）,4.,X.1,总体测试要求,4,.,X.2,测试类,4,.,X.3,测试级,4,.,X.4,测试定义,4,.,X.4.Y （,测试名称和项目唯一标识号）,4,.,X.5,测试进度,5,数据记录、整理和分析,5.10 软件测试说明（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,5.10 软件测试说明（二）,3 正式合格性测试准备,3.,X （,测试名称和项目唯一标识号）,3.,X.1 （,测试名称,）,进度,3,.,X.2 （,测试名称,）,测试准备过程,3,.,X.2.1,硬件要求,3,.,X.2.2,软件准备,3,.,X.2.3,其它测试准备,5.10 软件测试说明（三）,4,正式合格性测试说明,4.,X （,测试名称和项目唯一标识号）,4,.,X.Y（,测试用例名称和项目唯一标识号）,4,.,X.Y.1 (,测试用例的名称）需求可追踪性,4,.,X.Y.2 （,测试用例的名称）初始化,4,.,X.Y.3 （,测试用例的名称）测试输入,4,.,X.Y.4 （,测试用例的名称）期望测试结果,5.10 软件测试说明（四）,4.,X.Y.5 （,测试用例的名称）评估测试结果,的标准,4,.,X.Y.6 （,测试用例的名称）测试过程,4.,X.Y.7 （,测试用例的名称）前提和约束,5.11 软件测试报告（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,5.11 软件测试报告（二）,3 测试概述,3.1 （,正式合格性,测试名称及项目的唯一标识号）,3.1.1（,正式合格性,测试名称）小结,3.1.2（,正式合格性,测试名称）测试记录,5.11 软件测试报告（三）,4 测试结果,4.,X （,正式合格性,测试的名称和项目的唯,一标识号）测试结果,4.,X.Y（,测试用例名称和项目的唯一标识号,） 4,.,X.Y.1 （,测试用例名称,）测试结果,4,.,X.Y.2 （,测试用例名称,）测试过程中的,差异情况,5.11 软件测试报告（四）,5,CSCI,评估和建议,5.1,CSCI,评估,5.2 改进建议,5.12 计算机系统操作员手册（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,3 计算机系统操作,3.1 计算机系统准备和关机,5.12 计算机系统操作员手册（二）,3.1.1 通电和断电,3.1.2 启动,3.1.3 关机,3.2 操作过程,3.2.1 输入和输出过程,3.2.2 监督过程,故障和失效指示、联机干预等。,3.2.3 恢复过程,5.12 计算机系统操作员手册（三）,3.2.4 脱机程序过程,3.2.5 其它过程,4 诊断,4.1 诊断特征概要,陈述故障信息语法和故障隔离分级。,4.2 诊断过程,4.2.,X （,过程名,）,4,.3,诊断工具集,4.3.,X （,诊断工具名）,5.13 软件用户手册（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,3 执行过程,该执行过程应包括：,3.1 初始化,5.13 软件用户手册（二）,3.2 用户输入,3.3 系统输入,3.4 终止,终止软件的操作及判断是否正常终止。,3.5 重新启动,3.6 输出,描述预期输出和错误输出。,4 出错信息,5.14 软件程序员手册（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,5.14 软件程序员手册（二）,3 软件编程环境,3.1 设备配置,宿主机和目标机的部件和配置,3.2 操作信息,宿主机和目标机的操作特性、能力和,限制,3.3 编译、汇编和连接,设备和软件,5.14 软件程序员手册（三）,4 编程信息,4.1 编程特征,4.2 程序指令,4.3 输入和输出控制的编程,4.4 附加的或专用的技术,4.5 编程示例,4.6 错误检测和诊断功能,5.15 固件保障手册（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,5.15 固件保障手册（二）,3 固件设备信息,3.1 设备说明,3.2 安装和修理过程,3.3 安全保密性,3.4 限制,操作限制和环境限制,5.15 固件保障手册（三）,4 编程设备及其过程,4.1 编程用的硬件,编程和重新编程用的硬设备,4.2 编程用的软件,编程和重新编程用的软件,4.3 装入过程,编程和重新编程的过程，包括装入、验证和测试，及其所用的设备和软件。,5 销售方信息,5.16 计算机资源综合保障文件（一）,1 范围,1.1 标识,1.2 系统概述,1.3 文档概述,2 引用文档,5.16 计算机资源综合保障文件（二）,3 保障信息,3.1 软件保障资源,3.1.1 软件,3.1.2 硬件,3.1.3 设施,3.1.4 人员,3.1.5 其它资源,5.16 计算机资源综合保障文件（三）,3.2 操作,3.2.1 软件修改,3.2.2 软件集成和测试,3.2.3 软件生成,3.2.4 模拟,3.2.5 仿真,3.3 培训,3.4 预期的更改,4 转移计划,谢谢大家！,