软件工程推进方法

第六章软件工程标准化与文档写作

软件工程推进方法

李超成都信息工程学院

2005.6

第六章软件工程标准化与文档写作

软件文档是软件工程的一项重要内容，在软件生存周期中具有承上启下的作用，是软件工程各阶段的里程碑。软件文档的标准化是软件工程标准化的重点。本章的主要内容有：软件工程标准，软件文档编写步骤，软件文档的主要内容及写作要求，软件文档的管理。

第六章软件工程标准化与文档写作6.1 软件工程标准

软件工程作为一门工程技术，自然离不开标准。积极推行软件工程的标准化，可以使软件开发工作有章可循，从而提高软件质量、降低软件成本等。软件工程标准是软件工程发展的必然产物，也是人们对计算机软件认识深化的结果。在社会生活中，为了便于信息交流，有语言标准（如普通话）、文字标准（如汉字书写规范）等。同样，在软件工程项目中，为了便于项目内部不同人员之间和不同项目人员之间的信息交流，也要制订相应的标准，来规范软件开发过程和产品。

第六章软件工程标准化与文档写作6.1.1 软件工程标准的类型

软件工程标准的类型是多方面的，我国国家标准 GB/T15538-1995 《软件工程标准分类法》给出了软件工程标准的分类，包括：

过程标准（如方法、技术、度量等）——它同开发一个产品或从事一项服务的一系列活动或操作有关。产品标准（如需求、设计、部件、描述、计划、报告等）——它涉及事物的格式或内容。行业标准（如职业认证、许可、学习课程等）——它涉及软件工程行业的所有方面。记号标准（如术语、表示法、语言等）——它论述了在软件工程行业范围内，以唯一的一种方式进行交流的方法。

第六章软件工程标准化与文档写作6.1.1 软件工程标准的类型

软件工程标准的类型是多方面的，我国国家标准 GB/T15538-1995 《软件工程标准分类法》给出了软件工程标准的分类，包括：

过程标准（如方法、技术、度量等）——它同开发一个产品或从事一项服务的一系列活动或操作有关。产品标准（如需求、设计、部件、描述、计划、报告等）——它涉及事物的格式或内容。行业标准（如职业认证、许可、学习课程等）——它涉及软件工程行业的所有方面。记号标准（如术语、表示法、语言等）——它论述了在软件工程行业范围内，以唯一的一种方式进行交流的方法。

第六章软件工程标准化与文档写作6.1.2 软件工程标准的层次

根据软件工程标准制定的机构与适用范围的不同，可分为：1 、【国际标准】

由国际联合机构制订和公布、提供给各国参考的标准。ISO （ International Standards Organization ，国际标准化组织）是一个有着广泛的代表性和权威性的国际机构，它所公布的标准有较大的影响。如 ISO8631-86 《信息处理——程序构造及其表示法的约定》ISO9000 族标准


2 、【国家标准】由政府或国家级的机构制订或批准、适合于全国范围的标准。例如：(1) GB—— 中华人民共和国国家质量技术监督局是中国的最高标准化机构，其所公布的标准简称“国标”。

如 : GB8566-1995 《软件开发规范》 GB9385-88 《计算机软件需求说明编制指南》 GB9386-88 《计算机软件测试文件编制规范》

（ 2 ） ANSI(American National Standards Institute)—— 美国国家标准协会。（ 3 ） BS(British Standard)—— 英国国家标准。（ 4 ） DIN(Deutsches Institut fÜr Normung)——德国标准协会。（ 5 ） JIS(Japanese Industrial Standard)——日本工业标准。


3 、【行业标准】由行业机构、学术团体或国防机构制订的适合于某个行业的标准。例如：GJB—— 中华人民共和国国家军用标准。

如 :GJB437-88 《军用软件开发规范》GJB438-88 《军用软件文档编制规范》

IEEE （ Institute of Electrical and Electronics Engineers ）——美国电气与电子工程师学会。 IEEE 通过的标准经常要报请 ANSI审批，使之具有国家标准的性质。因此， IEEE 公布的标准常冠有 ANSI 的字头，如 :ANSI/IEEE828-1983 （《软件配置管理计划标

准》）


4 、【企业（机构）规范】大型企业或公司由于软件工程工作的需要而制订的适用于本部门的规范。例如，美国 IBM 公司通用产品部1984年制定的《程序设计开发指南》，仅供该公司内部使用。

5 、【项目（课题）规范】由某科研生产项目组织制订、且为该项任务专用的软件工程规范。例如：计算机集成制造系统（ CIMS ）的软件工程规范。

第六章软件工程标准化与文档写作6.1.3 软件工程国家标准

我国涉及软件工程度国家标准大致可以分为四类，即•基础标准•开发标准•文档标准•管理标准


表 6.1 软件工程国家标准分类标准名称标准号（相应国际标准）

基础标准

软件工程术语 GB/T 11457-95信息处理数据流程图、程序流程图、系统流程图、存在网络图和系统资源图的文件编辑符号及约定

GB 1526-89 （ ISO5807-85 ）

软件工程标准分类法 GB/T 15538-95(ANSI/IEEE1002)信息处理程序构造及其表示法的约定 GB 13502-92 （ ISO8631 ）信息处理单命中判定表规范 GB/T 15535-95 （ ISO5806-84 ）信息处理系统计算机系统配置图符号及其约定 GB/T 14085-93 （ ISO8790-87 ）



开发标准

信息技术软件生存期过程 GB/T 8566-95

计算机软件单元测试 GB/T 15532-95

软件支持环境 GB/T 15853-95

信息处理按记录组处理顺序文卷的程序流程 GB/T 15697-95 （ ISO6593-85 ）软件维护指南 GB/T 14079-93

DOS 中文信息处理系统接口 GB/T 15189-94



文档标准

软件文档管理指南 GB/T 16680-96 （ ISO/IEC TR9294-90 ）

计算机软件产品开发文件编制指南 GB/T

计算机软件需求说明编制指南 GB/T

计算机软件测试文件编制规范 GB/T



管理标准

计算机软件配置管理计划规范 GB/T

信息技术软件产品评价质量特性及其使用指南 GB/T

计算机软件质量保证计划规范 GB/T

计算机软件可靠性和可维护性管理 GB/T

计算机软件分类与代码 GB/T

信息技术软件包质量要求和测试 GB/T

工业控制软件评定准则 GB/T

第六章软件工程标准化与文档写作6.2 软件文档编写步骤

软件文档为提高软件工程项目的开发和管理能力提供了重要的基础。文档—是指某种数据媒体和其中所记录的数据。软件文档

记录了软件开发过程中的有关信息便于协调以后的软件开发、使用和维护作为软件开发人员在一定阶段的工作成果和结束的标志有利于及时纠正错误，提高软件开发效率有利于开发人员、管理人员以及用户等之间的协作和交流

第六章软件工程标准化与文档写作6.2 软件文档编写步骤要求及时性

实用性

规范性

完整性软件文档

第六章软件工程标准化与文档写作6.2 软件文档编写步骤分类

按照文档产生和使用的范围不同，软件文档可以分成三类，即技术文档、管理文档和用户文档。其中，技术文档和管理文档又统称为系统文档。1 、技术文档

技术文档是指着软件开发过程中作为开发人员前一阶段工作成果和后一阶段工作依据的文档。

第六章软件工程标准化与文档写作6.2 软件文档编写步骤分类1 、技术文档

可行性研究报告

主要包括详细设计说明书等

概要设计说明书数据要求说明书软件需求说明书1

2

3

4

5


分类2 、管理文档

管理文档是指软件开发过程中由开发人员等制订并提交给管理人员的工作计划或报告，使管理人员能够通过这些文档了解软件项目的安排；进度、资源使用及成果等。主要包括：项目开发计划测试计划测试报告开发进度月报项目开发总结等

第六章软件工程标准化与文档写作6.2 软件文档编写步骤分类3 、用户文档

这类文档是软件开发人员为用户准备的有关该软件使用、操作、维护的资料。主要包括：用户手册

操作手册

程序维护手册等


分类3 、用户文档不同规模软件与文档种类：按软件对应当源程序代码的行数不同，可以将软件规模分成四级，分别是：

① 小规模软件（源程序代码行数在 1万行以下）；② 中规模软件（源程序代码行数在 1 ～ 10万行之间）；③ 大规模软件（源程序代码行数在 10 ～ 50万行之间）；④ 特大规模软件（源程序代码行数在 50万行以上）。


不同规模软件文档的种类：小规模软件中规模软件大规模软件特大规模软件项目开发计划可行性研究报告可行性研究报告可行性研究报告

项目开发计划项目开发计划项目开发计划

软件需求说明书软件需求说明书软件需求说明书软件需求说明书数据需求说明书

测试计划测试计划测试计划

软件设计说明书软件设计说明书概要设计说明书概要设计说明书

详细设计说明书详细设计说明书模块开发卷宗数据库设计说明书


不同规模软件文档的种类：小规模软件中规模软件大规模软件特大规模软件用户手册用户手册用户手册用户手册

操作手册测试分析报告测试分析报告测试分析报告测试分析报告开发进度季报开发进度季报开发进度季报开发进度季报项目开发总结项目开发总结项目开发总结项目开发总结程序维护手册程序维护手册程序维护手册程序维护手册


软件文档编制与软件生存周期、使用者间的关系可行性研究与计划阶段

分析阶段设计阶段实现阶段测试阶段维护阶段使用者可行性研究报告 ▲ 管理员、开发人员项目开发计划书 ▲ ▲ 管理员、开发人员软件需求说明书 ▲ 开发人员数据要求说明书 ▲ 开发人员测试计划 ▲ ▲ 开发人员概要设计说明书 ▲ 开发人员、维护人员详细设计说明书 ▲ 开发人员、维护人员模块开发卷宗 ▲ ▲ 管理员、维护人员数据库设计说明书 ▲ 开发人员用户手册 ▲ ▲ ▲ 用户操作手册 ▲ ▲ 用户测试分析报告 ▲ 开发人员、维护人员开发进度月（季）报 ▲ ▲ ▲ ▲ ▲ 管理员项目开发总结 ▲ 管理员程序维护手册 ▲ 维护人员


软件文档的编写步骤：任何软件文档的编写过程都可分为四个步骤：1 、准备工作

准备工作的中心内容就是要准确理解和掌握目标系统的有关细节，对各种需求和要求进行分析研究，为确定写作内容打下基础。为了准确理解和掌握目标系统的有关细节，文档编制者可以采取座谈讨论、个别交谈、阅读相关材料等方法来获取有关信息，同时做好必要的记录。由于文档的使用者不同，其对文档的要求也不尽相同。文档的编写者必须在编写文档之前要明确文档的使用者及其对文档的要求。

2 、确定写作内容通过各种准备工作，文档的编写者已经收集到了丰富的写作信息。接下来便要确定编写文档的种类、文档内容的组织以及文档编写过程中应遵循的约定等。


软件文档的编写步骤：3 、编写定稿在编写软件文档时，应该注意两个方面：一是在文档编写过程中必须认真执行并采用有关标准、规定和约定，注意研究标准、规定和约定大合理表现方法；另外要充分利用现代化的软件文档编写工具，必要时可开发或完善有关文档编写管理工具。

编写者全面的修改编写者进行审核、校对评审申请组织评审通过评审

4 、更新完善软件系统的更新要及时反映到软件文档上

第六章软件工程标准化与文档写作6.3 软件文档的主要内容及写作要求

软件工程度主要软件文档大致有 15 种。对于具体的项目而言，文档的形式可能千差万别，但一些主要内容及写作要求则大体相似。主要依据国家标准 GB8567-88介绍软件文档的主要内容及写作要求

第六章软件工程标准化与文档写作6.3.1 可行性研究报告的主要内容及写作要求

1 、【引言】阐述编写目的、读者对象；介绍项目背景，包括项目名称、用户、开发者、用途、与其他系统或机构的关系等；列举有关参考资料（如任务书、合同、批文、技术标准等）和术语（如定义、英文缩写的原词组等）。2 、【可行性研究的前提】说明对所建议开发项目的基本要求（如功能、性能、输入 /输出、系统的基本处理流程和数据流程、安全性、保密性、与其他系统的关系、完成期限等）、开发目标（如工作效率的提高、成本的降低、生产质量或数量的提高等）、限定条件（如系统的使用寿命、开发时间长短、经费来源与限制、法律和政策的限制、运行环境与开发环境的限制等）、进行可行性研究的方法（如调查、加权、确定模型、仿真等）、评价尺度等。


3 、【对现有系统的分析】主要包括当前实际使用系统的处理流程和数据流程、工作负荷、费用开支、运行与维护人员的专业技术类别和数量、设备情况、主要问题和局限性等。4 、【所建议的系统】内容包括对所建议系统的说明、数据流程和处理流程、改进工作、影响（如对设备、软件、机构、运行、开发、经费开支等等影响）、局限性、技术条件方面的可行性等。5 、【可供选择的其他系统方案】扼要说明曾考虑过的每一种可选择的系统方案，并说明未被选择的理由。如果没有可供选择的系统方案，则应做出说明。


6 、【投资及收益分析】主要包括支出（如基本建设投资、其他一次性支出、非一次性支出等）、收益（如一次性收益、非一次性收益、不可定量的收益等）、收益 /投资比、投资回收期、敏感性分析等。7 、【社会条件方面的可行性】主要包括法律和使用等方面的可行性。8 、【结论】在进行可行性研究报告的编制时，必须提供一个研究的结论。结论可以是：

（ 1 ）立即进行（ 2 ）推迟到条件成熟后进行；（ 3 ）对开发目标进行某些修改后进行；（ 4 ）不能或不必进行。

第六章软件工程标准化与文档写作6.3.2 项目开发计划的主要内容及写作要求

1 、【引言】与《可行性研究报告》相似。

2 、【项目概述】阐述开发软件的主要功能、开发条件、运行环境、承办单位应交付的产品内容（如程序代码、文档资料）和应提供的服务、验收标准、完成项目的最迟期限、本计划的审查者与批准者等。

第六章软件工程标准化与文档写作6.3.2 项目开发计划的主要内容及写作要求

3 、【实施计划】包括任务分解、人员安排、工作进度、成本预算、关键问题等。

4 、【支持条件】包括计算机系统支持、需用户承担的工作、需外单位提供的条件等。

5 、【专项计划要点】包括测试计划、质量保证计划、人员培训计划、系统维护计划等。

第六章软件工程标准化与文档写作6.3.3 软件需求说明书的主要内容及写作要求


2 、【任务概述】包括被开发软件的主要组成、功能、编程语言、用户特点、一般约束等。

3 、【功能需求】用文字、图表或数学公式详细描述被开发软件的输入、处理、输出以及在上述过程中发生的基本操作等。

第六章软件工程标准化与文档写作6.3.3 软件需求说明书的主要内容及写作要求

4 、【外部接口需求】包括用户界面（如屏幕格式、菜单格式、命令格式、错误信息格式等）、硬件接口、软件接口等方面的要求。5 、【性能需求】如数据量大小、响应时间、结果精度等。6 、【软件属性需求】包括正确性、健壮性、安全保密性、可维护性等方面。7 、【数据需求】阐述系统中所有数据的输入、传输、存储、处理、输出特性等。如果是特大规模软件，则在数据要求说明书中单独说明。

第六章软件工程标准化与文档写作6.3.4 概要设计说明书的主要内容及写作要求


2 、【总体设计】描述被开发软件的物理实现方案、软件系统的总体结构、与其他系统或软件的接口等方面的内容。

3 、【模块设计】对总体结构中的各模块，简述模块的功能，说明对模块的性能要求，阐明模块间的接口特性等。

第六章软件工程标准化与文档写作6.3.4 概要设计说明书的主要内容及写作要求

4 、【数据结构设计】描述系统中数据的逻辑结构（如名称、数据项等）和物理结构（如存储要求、索引、访问方法等）的设计。5 、【运行设计】给出不同运行控制下各模块的组合方式、运行控制流和数据流，说明用户输入 /输出界面、操作方式等。6 、【故障处理说明】用表格的方式说明各种可能的错误或故障出现时系统输出的信息、含义及处理方法等。7 、【其他设计】包括安全保密性、可维护性等等设计。

第六章软件工程标准化与文档写作6.3.5 详细设计说明书的主要内容及写作要求


2 、【软件结构】列出软件的总体结构及模块划分结果。

3 、【模块设计说明】对某个模块，说明模块的具体功能、输入 /输出、算法过程、数据结构、存储分配、测试点等。

4 、【数据结构设计】描述数据的逻辑结构和物理结构的设计及数据结构与模块的关系。

第六章软件工程标准化与文档写作6.3.6 其他文档

1 、【数据要求说明书】给出数据的逻辑描述（如数据单元的名称、含义、度量单位、值域、格式和类型等）和数据采集的要求、范围、预处理以及对设备等等影响，为生成和维护系统的数据文件做准备。2 、【数据库设计说明书】对设计中的数据库的所有标识、逻辑结构和物理结构等作出具体规定，指导程序员的建库工作。3 、【用户手册】详细描述软件的功能、性能、用户界面、运行环境、使用规程、出错处理和恢复等，使用户了解如何使用该软件。


4 、【操作手册】为操作人员提供该软件的各种运行情况的有关知识，特别是操作细节。如果系统的人机界面比较友好，安装和操作比较简单，则可以并入用户手册中。5 、【模块开发卷宗】这是在模块开发过程中逐步编写出来的，每复审完一个模块或一组密切相关的模块时编写一份，记录和汇总低层次开发的进度和结果，以便于对整个模块开发工作的管理和复审，并为将来的维护提供有用的技术信息。主要包括模块开发情况表、功能说明、设计说明、源代码清单、测试说明和复审定结论等内容。6 、【测试计划】主要针对组装测试和确认测试，提供一个对该软件的测试安排，包括每项测试活动的内容、进度、条件、人员、测试用例的选择原则、测试结果允许多偏差范围等。


7 、【测试分析报告】主要包括测试计划的执行过程、测试时得到的结果、软件功能的实现情况、存在地缺陷和限制、出现的软件错误类型和级别等，以作为软件验收到依据之一。8 、【开发进度月（季）报】内容包括开发进度及成果、开发成本、技术难题、下一阶段的工作等。9 、【项目开发总结报告】阐述软件开发取得的成果、实现的功能、性能指标、所用的时间、总成本以及对软件开发工作的评价等。10 、【维护手册】内容包括维护项目的内容、原因，维护方法、步骤等。

第六章软件工程标准化与文档写作6.4 软件文档的管理

软件文档的管理主要有两个方面：

•文档编写过程度管理•文档使用过程度管理

第六章软件工程标准化与文档写作6.4.1 软件文档编写过程的管理

软件文档编写过程度管理主要有以下几个方面：1 、文档编写计划管理对于一个具体的系统，其负责人必须根据有关规定确定软件文档的编写计划，并指定专人负责。该计划主要包括：确定文档的种类、数量、详细程度、预期读者；明确文档的具体内容和要求；规定文档编制、审查、批准的负责人和有关手续；限定文档编制完成的时间和进度等。2 、文档编写进度管理包括编写与软件开发进度相适应的文档编写计划，明确提出未能按时完成进度时应采取得补救措施和办法。为了保证软件文档的编写进度与软件开发的进度同步，可在软件开发进度月（季）报上将软件文档编写进度情况同时反映出来，并进行相关考核。3 、文档评审管理软件文档评审管理主要是建立一套评审规则，明确评审定任务和责任。

第六章软件工程标准化与文档写作6.4.1 软件文档编写过程的管理

4 、文档维护管理在软件开发过程中，可能由于种种原因需要对有关文档进行修改。由于文档的重要性，修改时必须特别谨慎，尤其是主文本的修改。为此，可以按下述步骤和要求来严格控制文档的修改：

（ 1 ）提议。要求提出维护的有关人员填写维护建议表，说明待维护文档的名称、内容、位置及维护原因等。（ 2 ）评议。由有关人员对维护建议从维护的必要性、范围、方法、步骤、计划等方面进行评议。（ 3 ）审核。主要对维护的目的、要求、影响以及维护计划的可行性等进行审核。（ 4 ）批准。由有关人员批准维护计划，包括维护工作的先后顺序、维护内容及完成日期、执行标准等。（ 5 ）实施。由有关人员按维护计划进行维护，建立维护记录，产生新文档。

总的来说，对于一个系统，应该配有一名专职或兼职的文档管理人员进行文档管理工作，并成立相应组织，确保文档编写管理工作的顺利进行。

第六章软件工程标准化与文档写作6.4.2 软件文档使用过程的管理

软件文档的使用是软件文档编写的目的，其管理工作主要有以下几方面：1 、文档归档管理

文档归档要便于保存、查找和保密。例如，对文档按层次和保密级别进行分类组织。同时，正式文档必须有编写者、评审者、批准者的签字，并注明相应当日期。


2 、文档控制管理主要确保文档与系统、文档与文档的一致性以及文档的安全性。为此有如下要求：明确软件文档管理人员 , 由其负责保管系统全部文档主文本（两套）及有关文档或子集的发行使用情况记录。由软件文档管理人员负责文档的统一归档 ,确保归档文档符合归档要求。系统文档的两套主文本必须完全一致 , 其中一套可按规定手续办理借阅。文档子集必须与主文本一致 ,修改某子集必须先修改主文本。对文档子集分发与使用的情况必须进行记录 , 在必要时应收回。当文档被更新时 , 要及时注销原文档 ,整理主文本。


3 、文档发行管理软件文档的发行管理是软件文档使用的重要前提。在文档发行过程中，应该注意发行对象的选择与记录，做好文档更新、保密以及使用者反馈详细的记录与整理工作。软件文档作为一类配置项，应该纳入配置管理的范围，通过软件配置信息库对文档进行跟踪和控制。

第六章软件工程标准化与文档写作小结软件工程标准化是软件工程度重要内容之一，对于提高软件产品的性能价格比有重要的作用。软件工程标准有不同的种类和不同的层次，对应不同的应用范围，同时也覆盖了软件工程度方方面面。软件文档在软件开发过程中，既是前一阶段工作的成果，也是后一阶段工作的基础，因而是软件工程标准实施的一个重要方面。明确软件各阶段应该提交的文档，规范软件文档的写作步骤和内容，加强文档编写过程和使用过程度管理，对于保证文档、系统的一致性和完整性是极其关键的。软件文档的管理应该纳入软件配置的管理范围。

软 件 工 程 推 进 方 法

Documents

软件工程推进方法