软件工程文档完整规范版.docx

1、软件工程文档完整规范版软件工程文档模板附录A 软件需求分析报告文档模板 91. 范围本指南用于指导软件开发者为南京市交通局开发软件项目的过程，通过规范软件项目承担单位的开发过程达到提高软件质量，降低维护成本的目的。开发者应根据本指南进行软件开发和编制软件开发文档。本指南是对软件项目承担单位的基本要求.在本指南的附录A至E中提供了文档的编写模板供开发者参考，在进行具体软件开发时,开发者可根据实际情况采编写,但必须提供双方约定的文档，文档中约定的内容必须描述清楚。2. 总体要求2.1 总体功能要求网络应用环境以Internet/Intranet技术为核心。开发者应在充分分析需求的基础上，选择采用B

2、/S结构或者C/S结构。软件系统的数据库应依照南京市交通局信息化数据库建设规范进行设计和建设。本指南中没有规定开发者采用何种具体的软件工程开发方法，开发者可根据项目具体特点、自身擅长来选择采用面向过程的方法、面向对象的方法或面向数据的方法，但建议开发 商使用面向对象软件工程的方法,如：采用目前被广泛使用的RUP（Rational Unified Process）方法来进行分析、设计和开发.2.2 软件开发平台要求开发者开发的软件必须能够在南京市交通局规定的软件平台上正常运行。目前软件平台为：数据库管理系统：Oracle 9i以上版本中间件（应用服务器)系统：IBM WebSphereOA系统:

3、Lotus Domino/Notes网络架构:完全支持TCP/IP协议开发工具或技术体系：为保证软件的上下兼容性,开发者应选择比较通用的开发工具的较新版本进行开发，如Microsoft Visual Studio。Net,Borland Delphi，C+ Builder, 或J2EE(Java2 P1atform Enterprise Edition）等. 2.3 软件项目的开发实施过程管理要求2.3.1 软件项目实施过程总体要求（一）开发者提交软件开发工作大纲，交通局组织专家组对工作大纲进行评审，并提出整改意见.（二）通过评审后,开发者根据整改意见完善工作大纲，经过交通局认可后组织项目组进

4、行软件开发。软件开发工作按照需求分析、概要设计、详细设计、编码、测试等几个阶段进行，在开发过程中，开发者需分阶段提交相关文档。（三）在软件开发工作完成后，开发者应向交通局提交完整的软件文档，交通局组织验收组对软件进行验收审查.2.3.2 软件项目实施变更要求在开发过程中，需求或设计不可避免地需要发生变更，相关变更必须经过交通局书面同 意方可进行。在需求或设计发生变更时，需要对原有文档进行修改，并提供完整的变更记录， 以使变更处于可控制的状态。变更单如下表所示：表 21 变更单需求变更申请申请变更的需求文档 输入名称，版本,日期等信息变更的内客及其理由 评估需求变更将对项目造成的影响 申请人签字

5、 变更申请的审批意见项目经理签字 审批意见: 签字 日期 客户签字（合同项目） 审批意见： 签字 日期 更改需求文档变更后的需求文档 输入名称，版本,完成日期等信息 更改人签字 重新评审需求文档需求评审小组签字 评审意见： 签字 日期 变更结束项目经理签字 签字 日期 2.3.3 软件项目实施里程碑控制交通局将分四个阶段进行把关，召开专家审查会。（四） 需求分析（结合原型进行审查）确认;（五） 概要设计+数据库设计；（六） 预验收（试运行后）；（七） 正式验收（推广使用后）。3. 软件开发合同签订以后,项目承担单位即可组织项目组进行软件开发工作。软件开发必须严格按照软件工程的要求进行。开发过程

6、包括开发者的活动和任务。此过程由软件需求分析、概要设计、详细设计、编码、测试、验收、鉴定等活动组成。3.1 软件的需求分析3.1.1 需求分析首先,开发者和交通局应共同对交通局的应用需求作充分的调研,提交完整的需求分析 报告。在需求分析报告中必须描述的基本问题是:功能、性能、强加于实现的设计限制、属 性、外部接口.应当避免把设计或项目需求写入需求分析报告中.它必须说明由软件获得的 结果,而不是获得这些结果的手段.软件需求可以用若干种方法来表达,如通过输入、输出说明；使用代表性的例子；用规范化的模型。开发者应尽可能地使用模型的方式，因为这是表达复杂需求的精确和有效的方法。比如用统一建模语言(UM

7、L)来描述需求。编写需求分析报告的要求a无歧义性对最终产品的每一个特性用某一术语描述；若某一术语在某一特殊的行文中使用时具有多种含义，那么应对该术语的每种含义做出解释并指出其适用场合。b完整性需求分析报告应该包括全部有意义的需求，无论是关系到功能的、性能的、设计约束的、还是关系到外部接口方面的需求；对所有可能出现的输入数据的响应予以定义，要对合法和非合法的输入值的响应做出规定；填写全部插图、表、图示标记等；定义全部术语和度量单位。c可验证性需求分析报告描述的每一个需求应是可以验证的。可以通过一个有限处理过程来检查软件产品是否满足需求。d一致性在需求分析报告中的各个需求的描述不能互相矛盾。e可修

8、改性需求分析报告应具有一个有条不紊、易于使用的内容组织;没有冗余，即同一需求不能在需求分析报告中出现多次.f可追踪性每一个需求的源流必须清晰，在进一步产生和改变文件编制时,可以方便地引证每一个需求。g运行和维护阶段的可使用性需求分析报告必须满足运行和维护阶段的需要。在需求分析报告要写明功能的来源和目的.3.1.2 需求分析报告的编制者需求分析报告应由交通局和开发者双方共同完成。其中:交通局负责根据实际需要提出希望软件实现的功能;软件开发者根据交通局提出的性能需求,结合软件开发编写需求分析.3.1.3 需求报告评审在软件需求分析工作完成后，软件开发者应向交通局提交软件需求分析报告.交通局组织有关

9、人员对需求进行评审,以决定软件需求是否完善和恰当。评审完成后，就可以进入软件的设计阶段。3.1.4 需求报告格式软件需求分析报告需按一定的格式进行编写,具体的软件需求分析报告文档编写模板请见附录A。3.2 软件的概要设计3.2.1 概要设计在交通局和开发者双方认可的需求分析报告基础上，开发者进行下-步的工作。 首先，开发者需要对软件系统进行概要设计,即系统设计.概要设计需要对软件系统的设计 进行考虑,包括系统的基本处理流程、系统的组织结构、模块划分、功能分配、接口设计、 运行设计、数据结构设计和出错处理设计等,为软件的详细设计提供基础.3.2.2 编写概要设计的要求a一致性概要设计的要求应该与

10、需求分析报告所描述的需求一致。同时，概要设计的各项要求之间也应该一致。b合理性概要设计所提出的设计方法和标准应该是合理的、恰当的.c可追踪性对概要设计所提出的各项要求应该可以得到它的清晰的源流，即在需求分析报告客户有明确的需求描述。d可行性根据概要设计进行详细设计、操作和维护应该是可行的.3.2.3 概要设计报告的编写者概要设计报告由开发者根据需求分析报告的要求进行编写。3.2.4 概要设计和需求分析、详细设计之间的关系和区别 需求分析不涉及具体的技术实现,而概要设计注重于从宏观上和框架上来描述采用何种技术手段、方法来实现这些需求。详细设计相对概要设计更注重于微观上和框架内的设计, 是编码的依

11、据。概要设计是指导详细设计的依据。3.2.5 概要设计的评审在软件概要设计工作完成后,软件开发者应向交通提交软件系统概要设计报告.在交通局对概要设计报告评审通过后,即可进入详细设计阶段。3.2.6 概要设计格式软件系统概要设计报告需按一定的格式进行编写,具体的软件系统概要设计报 告文档编写模板请见附录B。3.3 软件的详细设计3.3.1 详细设计在概要设计的基础上，开发者需要进行软件系统的详细设计。在详细设计中，描述实 现具体模块所涉及到的主要算法、数据结构、类的层次结构及调用关系，需要说明软件系统各个层次中的每一个程序(每个模块或子程序)的设计考虑,以便进行编码和测试。应当保证 软件的需求完

12、全分配给整个软件。详细设计应当足够详细，能够根据详细设计报告进行编码。3.3.2 特例如果软件系统比较简单，层次较少,可以不必进行专门的详细设计,而和概要设计结合起来。3.3.3 详细设计的要求a一致性详细设计的要求应该与需求分析报告所描述的需求、与概要设计一致。同时，详细设计的各项要求之间也应该是一致的。b合理性详细设计所提出的设计方法和标准应该是合理的、恰当的。c可追踪性对详细设计所提出的各项要求应该可以得到它的清晰的源流,即可在需求分析报告、概要设计报告中有明确的需求描述.d可行性根据详细设计进行编码、测试、操作和维护应该是可行的。3.3.4 数据库设计如果软件产品需要使用到数据库，软件

13、的详细设计应包括对数据库的设计。数据库设计应在软件的需求分析、概要设计完成之后、详细设计的其它工作之前进行。在进行数据库设计时，应当按照交通局制定的南京市交通局信息化数据库建设规范要求进行。3.3.5 详细设计的评审在软件详细设计完成后,软件开发者应向交通局提交软件系统数据库设计报告和软件系统详细设计报告。在交通局对软件系统数据库设计报告、软件系统详细设计报告评审通过后,即可进入软件编码阶段.3.3.6 详细设计格式软件系统详细设计报告、软件系统数据库设计报告需按一定的格式进行编写， 具体的软件系统详细设计报告文档编写模板和软件系统数据库设计报告文档编写模 板请见附录C、附录D.3.4 软件的

14、编码3.4.1 软件编码在软件编码阶段,开发者根据软件系统详细设计报告中对数据结构、算法分析和模块实现等方面的设计要求,开始具体的编写程序工作,分别实现各模块的功能，从而实现对目标系统的功能、性能、接口、界面等方面的要求。3.4.2 软件编码的要求a模块化编码b代码可读性c可维护性d模块接口标准化e界面风格统一e注释的应用3.4.3 编码的评审为了尽早发现软件中的障碍,提高软件产品的质量，开发者在编码的过程中应该强调代码评审工作.将代码评审报告作为文档的一部分,提交给交通局。3.4.4 编程规范及要求为了提高编程实现的质量，软件的程序设计必须遵照国家颁布的相关编程规范。主要内容包括:规范化的程

15、序内部文档、数据结构的详细说明、清晰的语句结构、编码规范。编码规范的内容包括命名规范、界面规范、提示及帮助信息规范、热键定义等。其中数据库部分应遵守南京市交通局信息化数据库建设规范的要求。在软件编码的同时应进行单元测试。3.5 软件的测试3.5.1 软件测试为了尽早发现软件产品中的错误，从而达到提高软件质量、降低软件维护的费用，开发者应在编码过程中对各个模块的程序代码进行单元测试，系统集成时进行集成测试，系统集成完成后对整个软件进行系统测试。单元测试是在软件开发过程中针对程序模块进行正确性检验。集成测试是在单元测试的基础上，将所有模块按照设计要求组装成系统或子系统，对模块组装过程和模块接口进行

16、正确性检验。软件系统测试不仅是检测软件的整体行为表 现，从另一个侧面看，也是对软件开发设计的再确认。进行软件系统测试工作时.测试主要包括界面测试、可用性测试、功能测试、稳定性(强度)测试、性能测试、强壮性（恢复）测试、逻辑性测试、破坏性测试、安全性测试等。开发者针对单元测试，集成测试,系统测试分别制定测试计划。集成测试需要根据需求分析报告和概要设计制作测试用例，并须经过评审。软件测试按照测试计划、需求分析报告的要求进行，最后形成软件测试报告。3.5.2 测试计划在软件编码开始之前，开发者应向交通局提交测试计划,在软件交付时,开发者应向交通局提交软件测试报告，以确保开发者的软件得到了充分的测试.

17、开发的软件必须经过充分的测试证明其符合设计要求、运行稳定、安全可用方可交付交通局。3.6 软件的交付准备3.6.1 交付清单在软件测试证明软件达到要求后，软件开发者应向交通局提交开发的目标安装程序、数据库的数据字典、用户安装手册、用户使用指南、需求报告、设计报告、测试报告等双方合同约定的产物。用户安装手册应详细介绍安装软件对运行环境的要求、安装软件的定义和内容、在客户端、服务器端及中间件的具体安装步骤、安装后的系统配置。用户使用指南应包括软件各项功能的使用流程、操作步骤、相应业务介绍、特殊提示和注意事项等方面的内容，在需要时还应举例说明。3.7 软件的鉴定验收3.7.1 软件的鉴定验收在软件开

18、发完成后,为了确保软件是按照需求分析的要求进行开发的，保证软件产品的质量,需要对软件产品进行鉴定验收。在开发者如期交付软件后，由交通局负责确定具体的鉴定验收日期。3.7.2 验收人员由交通局聘请具有一定的分析、设计、编程和软件测试经验的验收组长和其他专业人员组成。验收组设组长一名（可设有副组长），负责整个验收的计划、组织工作。3.7.3 验收具体内容验收内容应该包括：合法性检查、文档检查、软件一致性检查、软件系统测试与测试结果评审等几项工作。合法性检查检查软件开发工具是否合法、使用的函数库、控件、组件是否有合法的发布许可。文档检查检查开发者提交的文档必须齐全，质量是否过关.需要开发者提供的文档

19、包括：项目实施计划；详细技术方案；软件需求规格说明书（STP）（含数据字典）;概要设计说明书（PDD);详细设计说明书（DDD）(含数据库设计说明书）；软件测试计划（STP）（含测试用例)；软件测试报告(STR）；用户手册(SUM）（含操作、使用、维护、应急处理手册)；源程序(SCL）(不可修改的电子文档）;项目实施计划（PIP）;项目开发总结（PDS);软件质量保证计划（SQAP）;此外，验收组可以根据需要对其它文档（如软件配置计划、项目进展报表、阶段评审报 表等）进行检查。文档的质量根据完备性、正确性、简明性、可追踪性、自说明性、规范件等方面进行踪合评定。验收需要对软件代码进行检查，以确保

20、其符合规范,并检查其一致性.3.7.4 软件验收测试大纲在软件进行鉴定验收前，开发者需按照一定的格式编写软件验收测试大纲，具体的格式请见附录E。3.8 培训3.8.1 系统应用培训主要培训内容包括：系统操作使用、业务管理流程.培训对象：应用操作人员.3.8.2 系统管理的培训(可选）主要培训内容包括：系统安装、调试、维护；系统管理。培训对象:系统管理人员.开发者应详细列出培训计划，包括培训内容、教材、时间和人员等。附录A 软件需求分析报告文档模板4. 引言引言是对这份软件产品需求分析报告的概览,是为了帮助阅读者了解这份文档是如何编写的，并且应该如何阅读、理解和解释这份文档。4.1 编写目的说明

21、这份软件产品需求分析报告是为哪个软件产品编写的，开发这个软件产品意义、作用、以及最终要达到的意图。通过这份软件产品需求分析报告详尽说明了该软件产品的需求规格，包括修正和（或）发行版本号,从而对该软件产品进行准确的定义。如果这份软件产品需求分析报告只与整个系统的某一部分有关系,那么只定义软件产品需求分析报告中说明的那个部分或子系统。4.2 项目风险具体说明本软件开发项目的全部风险承担者,以及各自在本阶段所需要承担的主要风险，首要风险承担者包括：任务提出者；软件开发者;产品使用者。4.3 文档约定描述编写文档时所采用的标准（如果有标准的话），或者各种排版约定.排版约定应该包括：正文风格；提示方式；

22、重要符号；也应该说明高层次需求是否可以被其所有细化的需求所继承，或者每个需求陈述是否都有其自己的优先级。4.4 预期读者和阅读建议列举本软件产品需求分析报告所针对的各种不同的预期读者，例如，可能包括：用户;开发人员;项目经理;营销人员；测试人员;文档编写入员。并且描述了文档中，其余部分的内容及其组织结构，并且针对每一类读者提出最适合的文档阅读建议。4.5 产品范围说明该软件产品及其开发目的的简短描述,包括利益和目标。把软件产品开发与企业目标，或者业务策略相联系。描述产品范围时需注意,可以参考项目视图和范围文档，但是不能将其内容复制到这里。4.6 参考文献列举编写软件产品需求分析报告时所用到的参

23、考文献及资料,可能包括：本项目的合同书；上级机关有关本项目的批文；本项目已经批准的计划任务书;用户界面风格指导;开发本项目时所要用到的标淮;系统规格需求说明；使用实例文档;属于本项目的其它己发表文件;本软件产品需求分析报告中所引用的文件、资料；相关软件产品需求分析报告；为了方便读者查阅，所有参考资料应该按一定顺序排列。如果可能，每份资料都应该给出：标题名称；作者或者合同签约者;文件编号或者版本号;发表日期或者签约日期；出版单位或者资料来源。5. 综合描述这一部分概述了正在定义的软件产品的作用范围以及该软件产品所运行的环境、使用该软件产品的用户、对该软件产品己知的限制、有关该软件产品的假设和依赖

24、.5.1 产品的状况描述了在软件产品需求分析报告中所定义的软件产品的背景和起源.说明了该软件产品是否属于下列情况：是否是产品系列中的下一成员；是否是成熟产品所改进的下一代产品；是否是现有应用软件的替代品(升级产品）；是否是一个新型的、自主型的产品.如果该软件产品需求分析报告定义的软件系统是:大系统的一个组成部分；与其它系统和其它机构之间存在基本的相互关系.那么必须说明软件产品需求分析报告定义的这部分软件是怎样与整个大系统相关联的,或者（同时)说明相互关系的存在形式,并且要定义出两者之间的全部接口.5.2 产品的功能因为将在需求分析报告的第4部分中详细描述软件产品的功能，所以在此只需要概略地总结

25、.仅从业务层面陈述本软件产品所应具有的主要功能,在描述功能时应该针对每一项需求准确地描述其各项规格说明。如果存在引起误解的可能,在陈述本软件产品主要功能的作用领域时，也需要对应陈述本软件产品的非作用领域，以利读者理解本软件产品。为了很好地组织产品功能，使每个读者都容易理解,可以采用列表的方法给出。也可以采用图形方式，将主要的需求分组以及它们之间的联系使用数据流程图的顶层图或类图进行表示,这种表示方法是很有用的。参考用户当前管理组织构架，了解各个机构的主要职能，将有助于陈述软件产品的主要功能。5.3 用户类和特性确定有可能使用该软件产品的不同用户类，并且描述它们相关的特征。往往有一些软件需求，只

26、与特定的用户类有关.描述时，应该将该软件产品的重要用户类与非重要用户类区分开.用户不一定是软件产品的直接使用者,通过报表、应用程序接口、系统硬件接口得到软件产品的数据和服务的人、或者机构也有他们的需求.所以,应该将这些外部需求视为通过报表、应用程序接口、系统硬件接口附加给软件产品的附加用户类。5.4 运行环境描述了本软件的运行环境,一般包括：硬件平台;操作系统和版本；支撑环境（例如：数据库等）和版本；其它与该软件有关的软件组件；与该软件共存的应用程序。5.5 设计和实现上的限制确定影响开发人员自由选择的问题,并且说明这些问题为什么成为一种限制。可能的限制包括下列内容：必须使用的特定技术、工具、

27、编程语言和数据库；避免使用的特定技术、工具、编程语言和数据库；要求遵循的开发规范和标准例如，如果由客户的公司或者第三方公司负责软件维护，就必须定义转包者所使用的设计符号表示和编码标准；企业策略的限制；政府法规的限制;工业标准的限制;硬件的限制例如，定时需求或存储器限制；数据转换格式标淮的限制.5.6 假设和约束（依赖）列举出对软件产品需求分析报告中，影响需求陈述的假设因素（与己知因素相对立）.如果这些假设因素不正确、不一致或者被修改，就会使软件产品开发项目受到影响。这些假设的因素可能包括:计划使用的商业组件，或者其它软件中的某个部件；假定产品中某个用户界面将符合一个特殊的设计约定；有关本软件用

28、户的若干假定（例如：假定用户会熟练使用SQL语言。）;有关本软件开发工作的若干假定(例如：用户承诺的优惠、方便、上级部门给予的特殊政策和支持等。)；有关本软件运行环境的一些问题;此外,确定本软件开发项目对外部约束因素所存在的依赖.有关的约束可能包括:工期约束;经费约束；人员约束;设备约束；地理位置约束；其它有关项目约束；6. 外部接口需求通过本节描述可以确定，保证软件产品能和外部组件正确连接的需求。关联图仅能表示高层抽象的外部接口，必须对接口数据和外部组件进行详细描述，并且写入数据定义中。如果产品的不同部分有不同的外部接口,那么应该把这些外部接口的全部详细需求并入到这一部分实例中。注意:必须将

29、附加用户类的特征与外部接口需求加以区分，附加用户类的特征描述的是通过接口取得软件产品的数据和服务的人的需求;而外部接口需求描述的是接口本身的需求。6.1 用户界面陈述需要使用在用户界面上的软件组件，描述每一个用户界面的逻辑特征。必须注意,这里需要描述的是用户界面的逻辑特征,而不是用户界面.以下是可能包括的一些特征:将要采用的图形用户界面（GUl)标准或者产品系列的风格；有关屏幕布局或者解决方案的限制；将要使用在每一个屏幕(图形用户界面）上的软件组件，可能包括:选单；标准按钮;导航链接；各种功能组件；消息栏；快捷键；各种显示格式的规定,可能包括：不同情况下文字的对齐方式；不同情况下数字的表现格式

30、与对齐方式日期的表现方法与格式；计时方法与时间格式;等等。错误信息显示标准；对于用户界面的细节，例如:一个特定对话框的布局,应该写入具体的用户界面设计说明中，而不能写入软件需求规格说明中。如果采用现成的、合适的用户界面设计规范（标准),或者另文描述，可以在这里直接说明，并且将其加入参考文献。6.2 硬件接口描述待开发的软件产品与系统硬件接口的特征，若有多个硬件接口,则必须全都描述。接口特征的描述内容可能包括:支持的硬件类型;软、硬件之间交流的数据；控制信息的性质;使用的通讯协议;6.3 软件接口描述该软件产品与其它外部组件的连接，这些外部组件必须明确它们的名称和版本号以资识别，可能的外部组件包括：操作系统；数据库；工具；函数库；集成的商业组件说明：这里所说的“集成的商业组件”,是指与系统集成的商业组件，而不是与软件产品集成的商业组件.例如:中间件、消息服务,等等.描述并且明确软件产品与软件组件之间交换数据或者消息的目的.描述所需要的服务,以及与内部组件通讯的性质。确定软件产品将与