软件文档写作标准讲义(ppt 55页)

软件文档写作,问题定义（书面）可行性分析报告（书面）项目开发计划（书面）需求规格说明书（书面）总体设计报告（书面）系统测试计划（书面）项目验收方案（书面）要求：根据软件工程技术和项目管理理念，在组内合理分工，协同工作。,软件文档文档是计算机软件产品的重要组成部分，没有文档就不成其为软件，也更不能成为软件产品。软件文档是一种重要的软件工程技术资料。如系统分析文档、设计文档、版本说明文档软件文档的规范编制，在软件开发工作中占有突出的地位和相当大的工作量。高质量、高效率的编制、分发、管理、维护文档，及时的变更、修正、扩充和使用文档，对于软件产品的设计开发、发行使用、变更维护、转让移植、二次开发等，对于充分发挥软件产品的效益，都有着重要的意义。,软件文档的分类,基于软件生存期方法，可以从形式上将软件文档大致分成两类：软件开发过程中需要填写的各种图表，及应编制的各种技术文件或管理资料。软件文档根据其产生和使用的范围，主要划分为3大类：开发文档、用户文档和管理文档。,软件文档,开发文档,用户文档,管理文档,可行性研究报告,项目开发计划,软件需求说明书,数据库设计说明书,概要设计说明书,详细设计说明书,用户手册,操作手册,软件需求说明书,数据要求说明书,项目开发计划,模块开发卷宗,开发进度月报,测试计划,测试分析报告,项目开发总结报告,开发文档,用户文档,软件文档的使用对象,开发人员,维护人员,管理人员,用户,可行性研究报告,项目开发计划,软件需求说明书,数据要求说明书,概要设计说明书,详细设计说明书,数据库设计说明书,测试计划,测试分析报告,设计说明书,测试分析报告,模块开发卷宗,可行性研究报告,项目开发计划,模块开发卷宗,开发进度月报,项目开发总结报告,用户手册,操作手册,软件生存周期各个阶段与各种文档编制的关系,文档所回答的问题,软件工程标准化和软件文档标准,软件工程标准编制的层次,根据软件工程标准制定的机构和标准适用的范围，可分为5个层次：国际标准:ISO国际标准化组织国家标准:GB中国ANSI美国BS英国JIS日本行业标准:IEEE企业(机构)标准:IBM项目(课题)标准:CIMS,文档表达,合理文档的7条规则,1.从读者的角度编写文档2.避免出现不必要的重复3.避免歧义4.使用标准结构5.记录基本原理6.使文档保持更新，但频度不要过高7.针对目标的适宜性对文档进行评审,下表是各类文档涉众以及他们需要的文档类型(部分)：,（1）用求和法确定应编制的文档,该方法的要点是提出12个考虑因素来衡量一个应用软件，以及每个因素可能取值的范围。任务负责人可用这12个因素对所要开发的程序进行衡量，以确定每个因素的具体值。然后，把这12个因素的值相加，得到一个总和，就可以根据这个总和的值，来确定应该编制的文档的种类。,然后，将上表衡量所得的各个因素的值相加，得总和值。再根据下表，确定应编制的文档种类。,文档的种类,因素值总和,表中：*，表示此文档应编制，但不必太正规；*，表示应根据所开发软件的实际需要来确定是否需要编制此文档。,（2）根据软件规模大小确定应编制的文档,为了避免在软件开发过程中文档编制的不足或过分，也为了避免前一种方法中对某些因素的把握出现误判，一个简便的方法是，把对软件文档的编制要求同软件的规模联系起来。这就是本例的出发点。这里，我们把软件的规模分为四级：(1)小规模软件，源码行数小于5000；(2)中规模软件，源码行数约1000050000；(3)大规模软件，源码行数约100000500000；(4)超大规模软件，源码行数大于500000。对此，相应规模软件应该编制的文档种类，参见下表：,对于源码行数在500010000、50000100000的软件，其文档编制的种类介于两级之间，可由项目负责人根据项目的具体情况，参照下表规定确定。,开发文档,概述,开发文档是描述软件开发过程，包括软件需求、软件设计、软件测试、保证软件质量的一类文档，开发文档也包括软件的详细设计描述(程序逻辑、程序间相互关系、数据格式和存储等)。,基本的软件开发文档主要有：,可行性研究和项目任务书需求规格说明功能规格说明设计规格说明，包括程序和数据规格说明开发计划软件集成和测试计划质量保证计划、标准、进度安全和测试信息,项目名称可行性研究报告拟制人_审核人_批准人_200年月日,可行性研究报告模板的例子：,1.引言1.1编写目的1.2背景1.3定义1.4参考资料2.可行性研究的前提2.1要求2.2目标2.3条件、假定和限制2.4进行可行性研究的方法2.5评价尺度3.对现有系统的分析3.1处理流程和数据流程3.2工作负荷3.3费用开支3.4人员3.5设备3.6局限性,4.所建议的系统4.1对所建议系统的说明4.2处理流程和数据流程4.3改进之处4.4影响4.4.1对设备的影响4.4.2对软件的影响4.4.3对用户单位机构的影响4.4.4对系统运行过程的影响4.4.5对开发的影响4.4.6对地点和设施的影响4.4.7对经费开支的影响4.5局限性4.6技术条件方面的可行性5.可选择的其他系统方案5.1可选择的系统方案15.2可选择的系统方案2,6.投资及效益分析6.1支出6.1.1基本建设投资6.1.2其他一次性支出6.1.3非一次性支出6.2收益6.2.1一次性收益6.2.2非一次性收益6.2.3不可定量的收益6.3收益投资比6.4投资回收周期6.5敏感性分析7.社会因素方面的可行性7.1法律方面的可行性7.2使用方面的可行性8.结论,软件需求文档的内容,1引言1.1编写的目的说明编写这份需求说明书的目的，指出预期的读者。1.2背景待开发的系统的名称；本项目的任务提出者、开发者、用户；该系统同其他系统或其他机构的基本的相互来往关系。1.3定义列出本文件中用到的专门术语的定义和外文首字母组词的原词组。1.4参考资料列出用得着的参考资料。,2任务概述2.1目标叙述该系统开发的意图、应用目标、作用范围以及其他应向读者说明的有关该系统开发的背景材料。解释被开发系统与其他有关系统之间的关系。2.2用户的特点列出本系统的最终用户的特点，充分说明操作人员、维护人员的教育水平和技术专长，以及本系统的预期使用频度。2.3假定和约束列出进行本系统开发工作的假定和约束。,3需求规定3.1对功能的规定用列表的方式，逐项定量和定性地叙述对系统所提出的功能要求，说明输入什么量、经怎么样的处理、得到什么输出，说明系统的容量,包括系统应支持的终端数和应支持的并行操作的用户数等指标。3.2对性能的规定3.2.1精度说明对该系统的输入、输出数据精度的要求，可能包括传输过程中的精度。3.2.2时间特性要求说明对于该系统的时间特性要求。3.2.3灵活性说明对该系统的灵活性的要求，即当需求发生某些变化时，该系统对这些变化的适应能力。,3.3输入输出要求解释各输入输出数据类型，并逐项说明其媒体、格式、数值范围、精度等。对系统的数据输出及必须标明的控制输出量进行解释并举例。3.4数据管理能力要求(针对软件系统)说明需要管理的文卷和记录的个数、表和文卷的大小规模，要按可预见的增长对数据及其分量的存储要求作出估算。3.5故障处理要求列出可能的软件、硬件故障以及对各项性能而言所产生的后果和对故障处理的要求。3.6其他专门要求如用户单位对安全保密的要求，对使用方便的要求，对可维护性、可补充性、易读性、可靠性、运行环境可转换性的特殊要求等。,4运行环境规定4.1设备列出运行该软件所需要的硬设备。说明其中的新型设备及其专门功能，包括：处理器型号及内存容量外存容量、联机或脱机、媒体及其存储格式，设备的型号及数量输入及输出设备的型号和数量，联机或脱机；数据通信设备的型号和数量功能键及其他专用硬件4.2支持软件列出支持软件，包括要用到的操作系统、编译程序、测试支持软件等。4.3接口说明该系统同其他系统之间的接口、数据通信协议等。,4.4控制说明控制该系统的运行的方法和控制信号，并说明这些控制信号的来源。,软件概要设计文档,结构化表现形式：层次图示例,简单的层次图缺乏追踪性，而HIPO图可以弥补此一缺点。,1.结构化表现形式,结构化表现形式：HIPO图,实际上，HIPO图是由H图和IPO图两部分组成：H图就是层次图；和H图每个方框相对应的，应该有一张IPO图描述该方框代表的模块的处理过程。如下图，是一个带编号的H图的例，具有可追踪性。,IPO图使用的符号既少又简单，能够方便的描述数据输入、处理和输出之间的关系。如下图是一个主文档更新的IPO例子。,图中，箭头清楚的指出了数据通信的情况。,结构化表现形式：结构图,Yourdon提出的结构图是进行软件结构设计的另一个有力的表达方法。而且，结构图较之层次图有更强的描述力。,结构化表现形式：结构图,结构图还有一些附加的符号，用以表示模块的选择调用和循环调用。如下图，左图是选择调用，右图是循环调用。,2、面向对象设计表现形式,（1）面向对象设计(OOD)的4个部分,这4个部分是问题域、人机交互部分、任务管理部分和数据管理部分。如下图所示。,-问题域部分：OOD根据需求分析中对问题域的描述，针对实现要求进行必要的整补和调整。其重点是：重用类设计、组合问题域专用类、调整继承的支持级别、提供数据管理部分以及增加底层细节。-人机交互部分设计：突出人如何命令系统，及系统如何向用户提交信息。尤其对非计算机专业用户如何提交信息。-任务管理部分设计：设计策略要点是识别并设计任务，加上包含在每个任务中的服务。-设计管理部分设计：该部分主要是为了隔离数据管理方案对系统设计表达的影响。设计既包含数据存放方法的设计，也包含相应服务的设计。,继承机制的表示,通常将父类放在上面，将子类放在下面。如左图,下图是表示鸡、鸭、猫、狗和动物之间的继承关系。,聚集关系的表示,若类B的定义将类A的对象作为数据成员，则B和A之间是一种聚集关系，其表示方法如下图所示。,对象关联的表示,内嵌关联结构表示,外嵌关联结构表示,注册/观察器的表示,一种将新的信息一对一的迅速传送或通知给相关对象的对象协作机制。特别在分布式环境中，对象通信代价很高时，这是一种高效的手段，在网络软件设计时常用。见下图例。,虚拟设备的表示,虚拟设备是操作系统的一个重要概念。使用这种概念，可以为在不同设备上实现相同功能，或以相同操作接口访问不同设备提供可能和方便。如图,代理结构的表示,代理是一种在应用和被访问对象之间建立的桥梁或关口。通过代理的虚拟作用，达到控制对象访问的目的。代理具有的作用或特性可以包括间接性、委托性、临时替代性、虚拟性、安全性/保护性、远程性和多源性。下图是代理模式的实现结构表示的例子。,网络代理连接的表示例子：,多源代理连接的例子,软件详细设计文档,软件详细设计文档,详细设计在概要设计之后，其工作重点是考虑实现各个模块的规定功能，表达的是模块内部的逻辑关系、数据结构和模块接口细节等，表达的方法主要有程序流程图、N-S图、PAD图、PDL语言以及判定表、树等。,程序流程图,程序流程图(ProgramFlowChart)的5种基本控制结构：,(1)顺序结构(sequentialstructure),(2)选择结构(selectivestructure),(3)先判定型循环结构(while-loopstructure),(4)后判定型循环结构(until-loopstructure),(5)多情况选择(casestructure),N-S图：,PAD图(ProblemAnalysisDiagram)：,日立公司，1973年提出。为ISO所极力推荐。也有5种基本控制结构。,PDL(ProgramDesignLanguage)：,是一种非正文形式的过程设计工具。PDL语言的特点：有固定的关键字外语法，有完整的结构化的控制结构、数据说明和模块特征；内语法使用自然语言描述处理特征，为使用者提供方便，提高可读性；有数据说明机制。包括简单的(标量和数组)和复杂的(链表和层次结构)数据结构；有子程序定义和调用机制，及各种方式的接口说明。,PDL示例,国标(GB8567-88)关于概要设计和详细设计的模板主要有：1.概要设计说明书2.数据库设计说明书3.组装测试计划4.详细设计说明书,管理文档,管理文档概述,工程化的软件生产方式是软件业界始终在不懈追求的目