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

引言

1、目的
一项计算机软件的筹划、研制及实现，构成一个软件开发项目。一个软件开发项目的进行，一般需要在人力和自动化资源等方面作重大的投资。为了保证项目开发的成功，最经济地花费这些投资，并且便于运行和维护，在开发工作的每一阶段，都需要编制二定的文件。这些文件连同计算机程序及数据一起，构成为计算机软件。文件是计算机软件中不可缺少的组成部分，它的作用是：
 a．作为开发人员在一定阶段内的工作成果和结束标志；
 b．向管理人员提供软件开发过程中的进展和情况，把软件开发过程中的一些“不可见的”事物转换成“可见的”文字资料。以便管理人员在各个阶段检查开发计划的实施进展，使之能够判断原定目标是否已达到，还将继续耗用资源的种类和数量；
 C．记录开发过程中的技术信息，便于协调以后的软件开发、使用和修改；
 d．提供对软件的有关运行、维护和培训的信息，便于管理人员、开发人员、操作人员和用户之间相互了解彼此的工作；
 e．向潜在用户报导软件的功能和性能，使他们能判定该软件能否服务于自己的需要。
 换言之，本指南认为：文件的编制必须适应计算机软件整个生存周期的需要。
 计算机软件所包含的文件有两类：一类是开发过程中填写的各种图表，可称之为工作表格；另一类则是应编制的技术资料或技术管理资料，可称之为文件。本指南规定软件文件的编制形式，并提供对这些规定的解释。本指南的目的是使得所编制的软件文件确实能够起到软件文件应该发挥的作用。
2、范围
本指南是一份指导性文件。本指甫建议，在一项计算机软件的开发过程中，一般地说，应该产生十四种文件。这十四种文件是：
 可行性研究报告；
 项目开发计划；
 软件需求说明书；
 数据要求说明书；
 概要设计说明书；
 详细设计说明书；
 数据库设计说明书；
 用户手册；
 操作手册；
 模块开发卷宗；
 测试计划；
 测试分析报告；
 开发进度月报；
 项目开发总结报告。
 本指南将给出开发过程中建议产生的这十四种文件的编制指导，同时，本指南也是这十四种文件的编写质量的检验准则。但是，本指南并未涉及软件开发过程中如何填写工作表格的问题。
 一般地说，一个软件总是一个计算机系统（包括硬件、固件和软件）的组成部分。鉴于计算机系统的多样性，本指南一般不涉及整个系统开发中的文件编制问题，本指南仅仅是软件开发过程中的文件编制指南。
3、文件的使用者
 对于使用文件的人员而言，他们所关心的文件的种类，随他们所承担的工作而异。
 管理人员：可行性研究报告，
 项目开发计划，
 模块开发卷宗，
 开发进度月报，
 项目开发总结报告；
 开发人员：可行性研究报告，
 项目开发计划，
 软件需求说明书，
 数据要求说明书，
 概要设计说明书，
 详细设计说明书，
 数据库设计说明书，
 测试计划，
 测试分析报告；
 维护人员：设计说明书，
 测试分析报告，
 模块开发卷宗；
 用户：用户手册，
 操作手册。
 尽管本指南提出了在软件开发中文件编制的要求，但并不意味着这些文件都必须交给用户。一项软件的用户应该得到的文件的种类由供应者与用户之间签订的合同规定。

第一篇文件的编制指导

4、软件生存周期与各种文件的编制
 一项计算机软件，从出现一个构思之日起，经过这项软件开发成功投入使用，直到最后决定停止使用，并被另一一项软件代替之时止，被认为是该软件的一个生存周期。一般地说这个软件生存周期可以分成以下六个阶段：可行性与计划研究阶段
需求分析阶段
设计阶段
实现阶段
测试阶段
运行与维护阶段
在可行性研究与计划阶段内，要确定该软件的开发目标和总的要求，要进行可行性分析、投资一收益分析、制订开发计划，并完成应编制的文件。
在需求分析阶段内，由系统分析人员对被设计的系统进行系统分析，确定对该软件的各项功能、性能需求和设计约束，确定对文件编制的要求，作为本阶段工作的结果，一般地说，软件需求说明书、数据要求说明书和初步的用户手册应该编写出来。
在设计阶段内，系统设计人员和程序设计人员应该在反复理解软件需求的基础上，提出多个设计，分析每个设计能履行的功能并进行相互比较，最后确定一个设计，包括该软件的结构、模块的划分、功能的分配以及处理流程。在被设计系统比较复杂的情况下，设计阶段应分解成概要设计阶段和详细设计阶段两个步骤。在一般情况下，应完成的文件包括：概要设计说明书、详细设计说明书和测试计划初稿。
在实现阶段内，要完成源程序的编码、编译（或汇编）和排错调试得到无语法错的程序清单，要开始编写模块开发卷宗，并且要完成用户手册、操作手册等面向用户的文件的编写工作，还要完成测试计划的编制。
在测试阶段，该程序将被全面地测试，已编制的文件将被检查审阅。一般要完成模块开发卷宗和测试分析报告，作为开发工作的结束，所生产的程序、文件以及开发工作本身将逐项被评价，最后写出项目开发总结报告。
在整个开发过程中（即前五个阶段中），开发集体要按月编写开发进度月报。
在运行和维护阶段，软件将在运行使用中不断地被维护，根据新提出的需求进行必要而且可能的扩充和删改。
对于一项软件而言，其生存周期各阶段与各种文件编写工作的关系可见表互，其中有些文件的编写工作可能要在若干个阶段中延续进行。

5文件编制中的考虑因素
 文件编制是一个不断努力的工作过程。是一个从形成最初轮廓，经反复检查和修改，直到程序和文件正式交付使用的完整过程。其中每一步都要求工作人员做出很大努力。要保证文件编制的质量，要体现每个开发项目的特点，也要注意不要花太多的人力。为此，编制中要考虑如下各项因素。
5.1文件的读者
 每一种文件都具有特定的读者。这些读者包括个人或小组、软件开发单位的成员或社会上的公众、从事软件工作的技术人员、管理人员或领导干部。他们期待着使用这些文件的内容来进行工作，例如设计、编写程序、测试、使用、维护或进行计划管理。因此，这些文件的作者必须了解自己的读者，这些文件的编写必须注意适应自己的特定读者的水平、特点和要求。
5．2重复性
 本指南第二篇中将列出的这十四种文件的内容要求中，显然存在某些重复。较明显的重复有两类。引言是每一种文件都要包含的内容，以向读者提供总的梗概。第二类明显的重复是各种文件中的说明部分，如对功能性能的说明、对输入和输出的描述、系统中包含的设备等。这是为了方便每种文件各自的读者，每种产品文件应该自成体系，尽量避免读一种文件时又不得不去参考另一种文件。当然，在每一种文件里，有关引言、说明等同其他文件相重复的部分，在行文上、在所用的术语上、在详细的程度上，还是应该有一些差别，以适应各种文件的不同读者的需要。
5．3灵活性
 鉴于软件开发是具有创造性的脑力劳动，也鉴于不同软件在规模上和复杂程度上差别极大，本指南认为在文件编制工作中应允许一定的灵活性。这种灵活性表现在如下各款。
5．3.1应编制的文件种类
 尽管本指南认为在一般情况下，一项软件的开发过程中，应产生的文件有十四种，然而针对一项具体的软件开发项目，有时不必编制这么多的文件，可以把几种文件合并成一种。一般地说，当项目的规模、复杂性和成败风险增大时，文件编制的范围、管理手续和详细程度将随之增加。反之，则可适当减少。为了恰当地掌握这种灵活性，本指南要求贯彻分工负责的原则，这意味着：
 a:一个软件开发单位的领导机构应该根据本单位经营承包的应用软件的专业领域和本单位的管理能力，制定一个对文件编制要求的实施规定，主要是：在不同的条件下，应该形成哪些文件？这些文件的详细程度？该开发单位的每一个项目负责人，必须认真执行这个实施规定。这种规定的两个例子可叹本指南的附录o（参考件）；
 b．对于一个具体的应用软件项目，项目负责人应根据上述实施规定，确定一个文件编制计划，主中包括:
 (1)应该编制哪几种文件，详细程度如何？
（2）各个文件的编制负责人和进度要求；
（3）审查、批准的负责人和时间进度安排；
（4）在开发时期内，各文件的维护、修改和管理的负责人，以及批准手续。
 每项工作必须落实到人。
 这个文件编制计划是整个开发计划的重要组成部分；
 C．有关的设计人员则必须严格执行这个文件编制计划。
5．3．2文件的详细程度
 从同一份提纲起草的文件的篇幅大小往往不同，可以少到几页，也可以长达几百页。对于这种差别本指南是允许的。此详细程度取决于任务的规模、复杂性和项目负责人对该软件的开发过程及运行环与所需要的详细程度的判断。
5．3.3文件的扩展
 当被开发系统的规模非常大（例如源码超过一百万行）时，一种文件可以分成几卷编写，可以按其。每一个系统分别编制，也可以按内容划分成多卷，例如：
 项目开发计划可能包括：质量保证计划，
 配置管理计划，
 用户培训计划，
 安装实施计划；
 系统设计说明书可分写成：系统设计说明书，
 子系统设计说明书；
 程序设计说明书可分写成：程序设计说明书，
 接口设计说明书，
 版本说明；
 操作手册可分写成：操作手册，
 安装实施过程；
．测试计划可分写成：测试计划，
 测试设计说明，
 测试规程，
 测试用例；
 测试分析报告可分写成：综合测试报告，
 验收测试报告；
 项目开发总结报告亦可分写成项目开发总结报告和资源环境统计。
5．3.4节的扩张与缩并
 在有些文件中，可以使用本指南所提供的章、条标题，但在条内又存在一系列需要分别讨论的因素本指南认为，所有的条都可以扩展，可以进一步细分，以适应实际需要。反之，如果章条中的有些细节；非必需，也可以根据实际情况缩并。此时章条的编号应相应地改变。
5．3.5程序设计的表现形式
 本指南对于程序的设计表现形式并未作出规定或限制，可以使用流程图的形式、判定表的形式，1可以使用其他表现形式，如程序设计语言（PDL）、问题分析图（PAD）等。
5．3.6文件的表现形式
 本指南对于文件的表现形式亦未作出规定或限制，可以使用自然语言，也可以使用形式化语言。
5．3.7文件的其他种类
 当本指南中规定的文件种类尚不能满足某些应用部门的特殊需要时，他们可以建立一些特殊的文件种类要求，例如软件质量保证计划、软件配置管理计划等，这些要求可以包含在本单位的文件编制实施规定中。

6文件编制的管理工作
 文件编制工作必须有管理工作的配合，才能使所编制的文件真正发挥它的作用。文件的编制工作实际上贯穿于一项软件的整个开发过程，因此，对文件的管理必须贯穿于整个开发过程。在开发过程中必须进行的管理工作是以下四条。
6．1文件的形成
 开发集体中的每个成员，尤其是项目负责人，应该认识到：文件是软件产品的必不可少的组成部分；在软件开发过程的各个阶段中，必须按照规定及时地完成各种产品文件的编写工作；必须把在一个开发步骤中作出的决定和取得的结果及时地写入文件；开发集体必须及时地对这些文件进行严格的评审；这些文件的形成是各个阶段开发工作正式完成的标志。这些文件上必须有编写者、评审者和批准者的签字，必须有编写、评审完成的日期和批准的日期。
6．2文件的分类与标识
 在软件开发的过程中，产生的文件是很多的，为了便于保存、查找、使用和修改，应该对文件按层次地加以分类组织。一个软件开发单位应该建立一个对本单位文件的标识方法，使文件的每一页都具有明确的标识。例如可以按如下四个层次对文件加以分类和标识。
 a．文件所属的项目的标识；
 b．文件种类的标识；
 C．同一种文件的不同版本号；
 d．页号。
 此外，对每种文件还应根据项目的性质，划定它们各自的保密级别，确定他们各自的发行范围。
6·3文件的控制
 在一项软件的开发过程中，随着程序的逐步形成和逐步修改，各种文件亦在不断地产生、不断地修改或补充。因此，必须加以周密的控制，以保持文件与程序产品的一致性，保持各种文件之间的一致性和文件的安全性。这种控制表现为：
 a．就从事一项软件开发工作的开发集体而言，应设置一位专职的文件管理人员（接口管理工程师或文件管理员）；在开发集体中，应该集中保管本项目现有全部文件的主文本两套，由该文件管理人员负责保管；
 b．每一份提交给文件管理人员的文件都必须具有编写人、审核人和批准人的签字；
 C．这两套主文本的内容必须完全一致；其中有一套是可供出借的，另一套是绝对不能出借的，以免发生万一；可出借的主文本在出借时必须办理出借手续，归还时办理注销出借手续；
 d．开发集体中的工作人员可以根据工作的需要，在本项目的开发过程中持有一些文件，即所谓个人文件，包括为使他完成他承担的任务所需要的文件，以及他在完成任务过程中所编制的文件；但这种个人文件必须是主文本的复制品，必须同主文本完全一致，若要修改，必须首先修改主文本；
 e·不同开发人员所拥有的个人文件通常是主文本的各种子集；所谓子集是指把主文本的各个部分根据承担不同任务的人员或部门的工作需要加以复制、组装而成的若干个文件的集合；文件管理人员。应该列出一份不同子集的分发对象的清单，按照清单及时把文件分发给有关人员或部门；
 f．一份文件如果已经被另一份新的文件所代替，则原文件应该被注销；文件管理人中要随时整理主文本，及时反映出文件的变化和增加情况，及时分发文件；
 g·当一个项目的开发工作临近结束时，文件管理人员应逐个收回开发集体内每个成员的个人文件，并检查这些个人文件的内容；经验表明，这些个人文件往往可能比主文本更详细，或同主文本的内容有所不同，必须认真监督有关人员进行修改，使主文本能真正反映实际的开发结果。
6．4文件的修改管理
在一个项目的开发过程中的任何时刻，开发集体内的所有成员都可能对开发工作的已有成果——文件，提出进行修改的要求。提出修改要求的理由可能是各种各样的，进行修改而引起的影响可能很小，也可能会牵涉到本项目的很多方面。因此，修改活动的进行必须谨慎，必须对修改活动的进行加以管理，必须执行修改活动的规程，使整个修改活动有控制地进行。
修改活动可分如下五个步骤进行：
a·提议开发集体中的任何一个成员都可以向项目负责人提出修改建议，为此应该填写一份修改建议表，说明修改的内容、所修改的文件和部位、以及修改理由；
b．评议由项目负责人或项目负责人指定的人员对该修改建议进行评议，包括审查该项修改的必要性、确定这一修改的影响范围、研究进行修改的方法、步骤和实施计划；
c．审核一般由项目负责人进行审核，包括核实修改的自的和要求、核实修改活动将带来的影响、审核修改活动计划是否可行；
d．批准在一般情况下，批准权属于该开发单位的部门负责人；在批准时，主要是决断修改工作中各项活动的先后顺序及各自的完成日期，以保证整个开发工作按原定计划日期完成；
e．实施由项目负责人按照已批准的修改活动计划，安排各项修改活动的负责人员进行修改，建立修改记录、产生新的文件以取代原有文件、最后把文件交文件管理人员归档，并分发给有关的持有者。