软件开发文档标准.docx
《软件开发文档标准.docx》由会员分享，可在线阅读，更多相关《软件开发文档标准.docx（44页珍藏版）》请在冰豆网上搜索。
软件开发文档标准
软件开发文档标准
一、计算机软件产品开发文件编制指南
1目的
一项计算机软件的筹划、研制与实现，构成一个软件开发项目。
一个软件开发项目的进行，一般需要在人力和自动化资源等方面作重大的投资。
为了保证项目开发的成功，最经济地花费这些投资，并且便于运行和维护，在开发工作的每一阶段，都需要编制二定的文件。
这些文件连同计算机程序与数据一起，构成为计算机软件。
文件是计算机软件中不可缺少的组成部分，它的作用是：
a.作为开发人员在一定阶段的工作成果和结束标志；
b.向管理人员提供软件开发过程中的进展和情况，把软件开发过程中的一些“不可见的”事物转换成“可见”的文字资料，以便管理人员在各个阶段检查开发计划的实施进展，使之能够判断原定目标是否已达到，还将继续耗用资源的种类和数量；
c.记录开发过程中的技术信息，便于协调以后的软件开发、使用和修改；
d.提供对软件的有关运行、维护和培训的信息，便于管理人员、开发人员、操作人员和用户之间相互了解彼此的工作；
e.向潜在用户报导软件的功能和性能，使他们能判定该软件能否服务于自己的需要。
换言之，本指南认为：
文件的编制必须适应计算机软件整个生存周期的需要。
计算机软件所包含的文件有两类：
一类是开发过程中填写的各种图表，可称之为工作表格；另一类则是应编制的技术资料或技术管理资料，可称之为文件。
本指南规定软件文件的编制形式，并提供对这些规定的解释。
本指南的目的是使得所编制的软件文件确实能够起到软件文件应该发挥的作用。
2围
本指南是一份指导性文件。
本指南建议，在一项计算机软件的开发过程中，一般地说，应该产生十四种文件。
这十四种文件是：
可行性研究报告；
项目开发计划；
软件需求说明书；
数据要求说明书；
概要设计说明书；
详细设计说明书；
数据库设计说明书；
用户手册；
操作手册；
模块开发卷宗；
测试计划；
测试分析报告；
开发进度月报；
本指南将给出开发过程中建议产生的这十四种文件的编制指导，同时，本指南也是这十四种文件的编写质量的检验准则。
但是，本指南并未涉与软件开发过程中如何填写工作表格的问题。
一般地说，一个软件总是一个计算机系统（包括硬件、固件和软件）的组成部分。
鉴于计算机系统的多样性，本指南一般不涉与整个系统开发中的文件编制问题，本指南仅仅是软件开发过程中的文件编制指南。
3文件的使用者
对于使用文件的人员而言，他们所关心的文件的种类，随他们所承担的工作而异。
管理人员：
可行性研究报告，项目开发计划，模块开发卷宗，开发进度月报，项目开发总结报告；
开发人员：
可行性研究报告，项目开发计划，软件需求说明书，数据要求说明书，概要设计说明书，详细设计说明书，数据库设计说明书，测试计划，测试分析报告；
维护人员：
设计说明书，测试分析报告，模块开发卷宗；
用户：
用户手册，操作手册。
尽管本指南提出了在软件开发中文件编制的要求，但并不意味着这些文件都必须交给用户。
一项软件的用户应该得到的文件的种类由供应者与用户之间签订的合同规定。
4软件生存周期与各种文件的编制
一项计算机软件，从出现一个构思之日起，经过这项软件开发成功投入使用，直到最后决定停止使用，并被另一一项软件代替之时止，被认为是该软件的一个生存周期。
一般地说这个软件生存周期可以分成以下六个阶段：
可行性与计算机研究阶段
需求分析阶段
设计阶段
实现阶段
测试阶段
运行与维护阶段
在可行性研究与计划阶段，要确定该软件的开发目标和总的要求，要进行可行性分析、投资一收益分析、制订开发计划，并完成应编制的文件。
在需求分析阶段，由系统分析人员对被设计的系统进行系统分析，确定对该软件的各项功能、性能需求和设计约束，确定对文件编制的要求，作为本阶段工作的结果，一般地说，软件需求说明书、数据要求说明书和初步的用户手册应该编写出来。
在设计阶段，系统设计人员和程序设计人员应该在反复理解软件需求的基础上，提出多个设计，分析每个设计能履行的功能并进行相互比较，最后确定一个设计，包括该软件的结构、模块的划分、功能的分配以与处理流程。
在被设计系统比较复杂的情况下，设计阶段应分解成概要设计阶段和详细设计阶段两个步骤。
在一般情况下，应完成的文件包括：
概要设计说明书、详细设计说明书和测试计划初稿。
在实现阶段，要完成源程序的编码、编译（或汇编）和排错调试得到无语法错的程序清单，要开始编写模块开发卷宗，并且要完成用户手册、操作手册等面向用户的文件的编写工作，还要完成测试计划的编制。
在测试阶段，该程序将被全面地测试，已编制的文件将被检查审阅。
一般要完成模块开发卷宗和测试分析报告，作为开发工作的结束，所生产的程序、文件以与开发工作本身将逐项被评价，最后写出项目开发总结报告。
在整个开发过程中（即前五个阶段中），开发集体要按月编写开发进度月报。
在运行和维护阶段，软件将在运行使用中不断地被维护，根据新提出的需求进行必要而且可能的扩充和删改。
对于一项软件而言，其生存周期各阶段与各种文件编写工作的关系可见表，其中有些文件的编写工作可能要在若干个阶段中延续进行。
5文件编制中的考虑因素
文件编制是一个不断努力的工作过程。
是一个从形成最初轮廓，经反复检查和修改，直到程序和文件正式交付使用的完整过程。
其中每一步都要求工作人员做出很大努力。
要保证文件编制的质量，要体现每个开发项目的特点，也要注意不要花太多的人力。
为此，编制中要考虑如下各项因素。
5.1 文件的读者
第一种文件都具有特定的读者。
这些读者包括个人或小组、软件开发单位的成员或社会上的公众、从事软件工作的技术人员、管理人员或领导干部。
他们期待着使用这些文件的容来进行工作，例如设计、编写程序、测试、使用、维护或进行计划管理。
因此，这些文件的作者必须了解自己的读者，这些文件的编写必须注意适应自己的特定读者的水平、特点和要求。
5.2 重复性
本指南第二篇中将列出的这十四种文件的容要求中，显然存在某些重复。
较明显的重复有两类。
引言是第一种文件都要包含的容，以向读者提供总的梗概。
第二类明显的重复是各种文件中的说明部分，如对功能性能的说明、对输入和输出的描述、系统中包含的设备等。
这是为了方便每种文件各自的读者，每种产品文件应该自成体系，尽量避免读一种文件时又不得不去参考另一种文件。
当然，在每一种文件里，有关引言、说明等同其他文件相重复的部分，在行文上、在所用的术语上、在详细的程度上，还是应该有一些差别，以适应各种文件的不同读者的需要。
5.3 灵活性
鉴于软件开发是具有创造性的脑力劳动，也鉴于不同软件在规模上和复杂程序上差别极大，本指南认为在文件编制工作中应允许一定的灵活性。
这种灵活性表现在如下各款。
5.3.1 应编制的文件种类
尽管本指南认为在一般情况下，一项软件的开发过程中，应产生的文件有十四种，然而针对一项具体的软件开发项目，有时不必编制这么多的文件，可以把几种文件合并成一种。
一般地说，当项目的规模、复杂性和成败风险增大时，文件编制的围、管理手续和详细程度将随之增加。
反之，则可适当减少。
为了恰当地掌握这种灵活性，本指南要求贯彻分工负责的原则，这意味着：
a.一个软件开发单位的领导机构应该根据单位经营承包的应用软件的专业领域和本单位的管理能力，制定一个对文件编制要求的实施规定，主要是：
在不同的条件下，应该形成哪些文件？
这些文件的详细程序？
该开发单位的每一个项目负责人，必须认真执行这个实施规定。
这种规定的两个例子可看本指南的附录；
b.对于一个具体的应用软件项目，项目负责人应根据上述实施规定，确定一个文件编制计划，主要包括：
（1）应该编制哪几种文件，详细程序如何？
（2）各个文件的编制负责人和进度要求；
（3）审查、批准的负责人和时间进度安排；
（4）在开发时期，各文件的维护、修改和管理的负责人，以与批准手续。
每项工作必须落实到人。
这个文件编制计划是整个开发计划的重要组成部分；
c.有关的设计人员则必须严格执行这个文件编制计划。
5.3.2 文件的详细程序
从同一份提纲起草的文件的篇幅大小往往不同，可以少到几页，也可以长达几百页。
对于这种差别本指南是允许的。
此详细程序取决于任务的规模、复杂性和项目负责人对该软件的开发过程与运行环与所需要的详细程度的判断。
5.3.3 文件的扩展
当被开发系统的规模非常大（例如源码超过一百万行）时，一种文件可以分成几卷编写，可以按其。
每一个系统分别编制，也可以按容划分成多卷，例如：
项目开发计划可能包括：
质量保证计划，配置管理计划，用户培训计划，安装实施计划；
系统设计说明书可分写成：
系统设计说明书，子系统设计说明书；
程序设计说明书可分写成：
程序设计说明书，接口设计说明书，版本说明；
操作手册可分写成：
操作手册，安装实施过程；
测试计划可分写成：
测试计划，测试设计说明，测试规程，测试用例；
测试分析报告可分写成：
综合测试报告，验收测试报告；
项目开发总结报告亦可分写成项目开发总结报告和资源环境统计。
5.3.4 节的扩与缩并
在有些文件中，可以使用本指南所提供的章、条标题，但在条又存在一系列需要分别讨论的因素本指南认为，所有的条都可以扩展，可以进一步细分，以适应实际需要。
反之，如果章条中的有些细节；非必需，也可以根据实际情况缩并。
此时章条的编号应相应地改变。
5.3.5 程序设计的表现形式
本指南对于程序的设计表现形式并未作出规定或限制，可以使用流程图的形式、判定表的形式，可以使用其他表现形式，如程序设计语言（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.实施由项目负责人按照已批准的修改活动计划，安排各项修改活动的负责人员进行修改，建立修改记录、产生新的文件以取代原有文件、最后把文件交文件管理人员归档，并分发给有关的持有者。
二、可行性研究报告
可行性研究报告的编写目的是：
说明该软件开发项目的实现在技术、经济和社会条件方面的可行性；评述为了合理地达到开发目标而可能选择的各种方案；说明并论证所选定的方案。
可行性研究报告的编写容要求如下：
1引言
1.1 编写目的
说明编写本可行性研究报告的目的，指出预期的读者。
1.2 背景
说明：
a.所建议开发的软件系统的名称；
b.本项目的任务提出者、开发者、用户与实现该软件的计算中心或计算机网络；
c.该软件系统同其他系统或其他机构的基本的相互来往关系。
1.3 定义
列出本文件中用到的专门术语的定义和外文首字母组词的原词组。
1.4 参考资料
列出用得着的参考资料，如：
a.本项目的经核准的计划任务书或合同、上级机关的批文；
b.属于本项目的其他已发表的文件；
c.本文件中各处引用的文件、资料，包括所需用到的软件开发标准。
列出这些文件资料的标题、文件编号、发表日期和出版单位，说明能够得到这些文件资料的来源。
2可行性研究的前提
说明对所建议的开发项目进行可行性研究的前提，如要求、目标、假定、限制等。
2.1 要求
说明对所建议开发的软件的基本要求，如：
a.功能；
b.性能；
c.输出如报告、文件或数据，对每项输出要说明其特征，如用途、产生频度、接口以与分发对象；
d.输入说明系统的输入，包括数据的来源、类型、数量、数据的组织以与提供的频度；
e.处理流程和数据流程用图表的方式表示出最基本的数据流程和处理流程，并辅之以叙述；
f.在安全与方面的要求；
g.同本系统相连接的其他系统；
h.完成期限。
2.2 目标
说明所建议系统的主要开发目标，如：
a.人力与设备费用的减少；
b.处理速度的提高；
c.控制精度或生产能力的提高；
d.管理信息服务的改进；
e.自动决策系统的改进；
f.人员利用率的改进。
2.3 条件、假定和限制
说明对这项开发中给出的条件、假定和所受到的限制，如：
a．所建议系统的运行寿命的最小值；
b．进行系统方案选择比较的时间；
c．经费、投资方面的来源和限制；
d．法律和政策方面的限制；
e．硬件、软件、运行环境和开发环境方面的条件和限制；
f．可利用的信息和资源；
g.系统投入使用的最晚时间。
2.4 进行可行性研究的方法
说明这项可行性研究将是如何进行的，所建议的系统将是如何评价的。
摘要说明所使用的基本方法和策略，如调查、加权、确定模型、建立基准占或仿真等。
2.5 评价尺度
说明对系统进行评价时所使用的主要尺度，如费用的多少、各项功能的优先次序、开发时间的长短与使用中的难易程序。
3对现有系统的分析
这里的现有系统是指当前实际使用的系统，这个系统可能是计算机系统，也可能是一个机械系统甚至是一个人工系统。
分析现有系统的目的是为了进一步阐明建议中的开发新系统或修改现有系统的必要性。
3.1 处理流程和数据流程
说明现有系统的基本的处理流程和数据流程。
此流程可用图表即流程图的形式表示，并加以叙述。
3.2 工作负荷
列出现有系统所承担的工作与工作量。
3.3 费用开支
列出由于运行现有系统所引起的费用开支，如人力、设备、空间、支持性服务、材料等项开支以与开支总额。
3.4 人员
列出为了现有系统的运行和维护所需要的人员的专业技术类别和数量。
3.5 设备
列出现有系统所使用的各种设备。
3.6 局限性
列出本系统的主要的局限性，例如处理时间赶不上需要，响应不与时，数据存储能力不足，处理功能不够等。
并且要说明，为什么对现有系统的改进性维护已经不能解决问题。
4所建议的系统
本章将用来说明所建议系统的目标和要求将如何被满足。
4.1 对所建议系统的说明
概括地说明所建议系统，并说明在第A．2章中列出的那些要求将如何得到满足，说明所使用的基本方法与理论根据。
4.2 处理流程和数据流程
给出所建议系统的处理流程和数据流程。
4.3 影响
说明在建立所建议系统时，预期将带来的影响，包括：
4.4.1 对设备的影响
说明新提出的设备要求与对现存系统可使用的设备须作出的修改。
4.4.2 对软件的影响
说明为了使现存的应用软件和支持软件能够同所建议系统相适应。
而需要对这些软件所进行的修改和补充。
4.4.3 对用户单位机构的影响
说明为了建立和运行所建议系统，对用户单位机构、人员的数量和技术水平等方面的全部要求。
4.4.4 对系统运行过程的影响
说明所建议系统对运行过程的影响，如：
a．用户的操作规程；
b．运行中心的操作规程；
c．运行中心与用户之间的关系；
d．源数据的处理；
e．数据进入系统的过程；
f．对数据保存的要求，对数据存储、恢复的处理；
g．输出报告的处理过程、存储媒体和调度方法；
h．系统失效的后果与恢复的处理办法。
4.4.5 对开发的影响
说明对于开发的影响，如：
a．为了支持所建议系统的开发，用户需进行的工作；
b．为了建立一个数据库所要求的数据资源；
c．为了开发和测验所建议系统而需要的计算机资源；
d．所涉与的与安全问题。
4.4.6 对地点和设施的影响
说明对建筑物改造的要求与对环境设施的要求。
4.4.7 对经费开支的影响
扼要说明为了所建议系统的开发，设计和维持运行而需要的各项经费开支。
4.5 局限性
说明所建议系统尚存在的局限性以与这些问题未能消除的原因。
4.6 技术条件方面的可行性
本节应说明技术条件方面的可行性，如：
a．在当前的限制条件下，该系统的功能目标能否达到；
b．利用现有的技术，该系统的功能能否实现；
c．对开发人员的数量和质量的要求并说明这些要求能否满足；
d．在规定的期限，本系统的开发能否完成。
5可选择的其他系统方案
扼要说明曾考虑过的每一种可选择的系统方案，包括需开发的和可从国国外直接购买的，如果没有供选择的系统方案可考虑，则说明这一点。
5．1可选择的系统方案1
参照第4章的提纲，说明可选择的系统方案1，并说明它未被选中的理由。
5．2可选择的系统方案2
按类似5．1条的方式说明第2个乃至第。
个可选择的系统方案。
6投资与效益分析
6．1支出
对于所选择的方案，说明所需的费用。
如果已有一个现存系统，则包括该系统继续运行期间所需的费用。
6．1．1基本建设投资
包括采购、开发和安装下列各项所需的费用，如：
a．房屋和设施；
b．ADP设备；
c．数据通讯设备；
d．环境保护设备；
e．安全与设备；
f．ADP操作系统的和应用的软件；
g．数据库管理软件。
6．1．2其他一次性支出
包括下列各项所需的费用，如：
a．研究（需求的研究和设计的研究）；
b．开发计划与测量基准的研究；
c．数据库的建立；
d．ADP软件的转换；
e．检查费用和技术管理性费用；
f．培训费、旅差费以与开发安装人员所需要的一次性支出；
g．人员的退休与调动费用等。
6．1．3非一次性支出
列出在该系统生命期按月或按季或按年支出的用于运行和维护的费用，包括：
a．设备的租金和维护费用；
b.软件的租金和维护费用；
c．数据通讯方面的租金和维护费用；
d．人员的工资、奖金；
e．房屋、空间的使用开支；
f．公用设施方面的开支；
g．安全方面的开支；
h．其他经常性的支出等。
6．2收益
对于所选择的方案，说明能够带来的收益，这里所说的收益，表现为开支费用的减少或避免、差错的减少、灵活性的增加、动作速度的提高和管理计划方面的改进等，包括；
6．2．1一次性收益
说明能够用人民币数目表示的一次性收益，可按数据处理、用户、管理和支持等项分类叙述，如：
a．开支的缩减包括改进了的系统的运行所引起的开支缩减，如资源要求的减少，运行效率的改进，数据进入、存贮和恢复技术的改进，系统性能的可监控，软件的转换和优化，数据压缩技术的采用，处理的集中化／分布化等；
b．价值的增升包括由于一个应用系统的使用价值的增升所引起的收益，如资源利用的改进，管理和运行效率的改进以与出错率的减少等；
c．其他如从多余设备出售回收的收入等。
6．2．2非一次性收益
升级会员 