2022年软件文档写作标准讲义.pptx

Click to edit Master title style,Click to edit Master text styles,Second level,Third level,Fourth level,Fifth level,11/7/2009,#,单击此处编辑母版标题样式,单击此处编辑母版文本样式,第二级,第三级,第四级,第五级,*,*,软件文档写作,问题定义（书面）,可行性分析报告（书面）,项目开发计划,（书面）,需求规格说明书（书面）,总体设计报告（书面）,系统测试计划（书面）,项目验收方案（书面）,要求：,根据软件工程技术和项目管理理念，在组内合理分工，协同工作。,软件文档,文档是计算机软件产品的重要组成部分，没有文档就不成其为软件，也更不能成为软件产品。,软件文档是一种重要的软件工程技术资料。如系统分析文档、设计文档、版本说明文档,软件文档的规范编制，在软件开发工作中占有突出的地位和相当大的工作量。高质量、高效率的编制、分发、管理、维护文档，及时的变更、修正、扩充和使用文档，对于软件产品的设计开发、发行使用、变更维护、转让移植、二次开发等，对于充分发挥软件产品的效益，都有着重要的意义。,软件文档的分类,基于软件生存期方法，可以从,形式上,将软件文档大致,分成两类：,软件开发过程中需要填写的各种图表，及应编制的各种技术文件或管理资料。,软件文档根据其产生和使用的范围，主要划分为3大类：,开发文档、用户文档和管理文档。,软件文档,开发文档,用户文档,管理文档,可行性研究报告,项目开发计划,软件需求说明书,数据库设计说明书,概要设计说明书,详细设计说明书,用户手册,操作手册,软件需求说明书,数据要求说明书,项目开发计划,模块开发卷宗,开发进度月报,测试计划,测试分析报告,项目开发总结报告,开发文档,用户文档,软件文档的使用对象,开发人员,维护人员,管理人员,用 户,可行性研究报告,项目开发计划,软件需求说明书,数据要求说明书,概要设计说明书,详细设计说明书,数据库设计说明书,测试计划,测试分析报告,设计说明书,测试分析报告,模块开发卷宗,可行性研究报告,项目开发计划,模块开发卷宗,开发进度月报,项目开发总结报告,用户手册,操作手册,可行性研究与计划,需求分析,软件设计,编码与单元测试,集成与测试,运行与维护,可行性研究报告,项目开发计划,软件需求说明书,数据要求说明书,测试计划,概要设计说明书,详细设计说明书,数据库设计说明书,模块开发卷宗,用户手册,操作手册,测试分析报告,开发进度月报,项目总结报告,维护和修改建议,软件生存周期各个阶段与各种文档编制的关系,为什么,(,Why,),做什么,(,What,),怎么做,(,How,),谁来做,(,Who,),何时做,(,When,),何处做,(,Where,),可行性研究报告,项目开发计划,软件需求说明书,数据要求说明书,测试计划,概要设计说明书,详细设计说明书,数据库设计说明书,模块开发卷宗,用户手册,操作手册,测试分析报告,开发进度月报,项目总结报告,维护和修改建议,文档所回答的问题,软件工程标准化和软件文档标准,软件工程标准编制的层次,根据软件工程标准制定的机构和标准适用的范围，可分为5个层次：,国际标准:,ISO 国际标准化组织,国家标准:,GB中国ANSI美国BS英国JIS日本,行业标准:,IEEE,企业(机构)标准:,IBM,项目(课题)标准:,CIMS,类型,标准名称,标准号,基,础,标,准,软件工程术语,GB/T 11457-1989,信息处理数据流程、程序流程图、系统结构图、程序网络图、系统资源图的文件编制符号及约定,GB/T 1526-1989,软件工程标准分类法,GB/T 15538-1995,信息处理程序构造及其表示法的约定,GB/T 13502-1992,信息处理单命中判定表规范,GB/T 15535-1995(ISO 5806),信息处理系统计算机系统配置图符号及其约定,GB/T 14085-1993(ISO 8790),开,发,标,准,信息技术软件生存期过程,GB/T 8566-1995,软件支持环境,GB/T 15853-1995,信息处理按记录组处理顺序文卷的程序流程,GB/T 15697-1995(ISO 6593),软件维护指南,GB/T 14079-1993,文,档,标,准,计算机软件产品开发文档编制指南,GB/T 8567-1988,计算机软件需求说明编制指南,GB/T 9385-1988,计算机软件测试文档编制规范,GB/T 9386-1988,软件文档管理指南,GB/T 16680-1996,管,理,标,准,计算机软件配置管理计划规范,GB/T 12505-1990,信息技术软件产品评价质量特性及其使用指南,GB/T 16260-1996,计算机软件质量保证计划规范,GB/T 12504-1990,计算机软件可靠性和可维护性管理,GB/T 14394-1993,文档表达,合理文档的7条规则,1.从读者的角度编写文档,2.避免出现不必要的重复,3.避免歧义,4.使用标准结构,5.记录基本原理,6.使文档保持更新，但频度不要过高,7.针对目标的适宜性对文档进行评审,下表是各类文档涉众以及他们需要的文档类型(部分)：,开发人员,维护人员,管理人员,营销人员,用户,可行性研究报告,项目开发计划,软件需求说明书,数据要求说明书,测试计划,概要设计说明书,详细设计说明书,数据库设计说明书,模块开发卷宗,用户手册,操作手册,测试分析报告,开发进度月报,项目总结报告,维护和修改建议,产品市场宣传资料,（1）用求和法确定应编制的文档,该方法的要点是提出12个考虑因素来衡量一个应用软件，以及每个因素可能取值的范围。任务负责人可用这12个因素对所要开发的程序进行衡量，以确定每个因素的具体值。然后，把这12个因素的值相加，得到一个总和，就可以根据这个总和的值，来确定应该编制的文档的种类。,编号,因 素,因 素 取 值,1,2,3,4,5,1,创新程度,没有在不同设备上重编程序,有限只是具有更严格的要求,很多具有新的接口,大量应用新的现代开发技术,重大应用先进的开发和管理技术,2,通用程度,很强的限制单一项目,有限制功能的范围是参量化的,有限的灵活性，允许格式上有些变化,多用途、灵活的格式、有主题领域,很灵活能在不同设备上处理范围广泛的主题,3,应用范围,局部单位(团以下),本地应用(师级),行业推广(军级),全国推广(大军区),国际项目(全军范围),4,应用环境的变化,没有,很少,偶尔有,经常,不断,5,设备复杂性,单机、常规处理,单机、常规处理、扩充的外设系统,多机、标准的外设系统,多机、复杂准的外设系统和显示,主机控制系统多机自动I/O,6,参加开发人数,12人,35人,613人,1118人,19以上,7,开发投资(人月),360,8,重要程度,一般数据处理,常规过程控制,人身安全,单位成败,国家安危,9,完成程序修改的平均时间,2周以上,12周,37天,13天,24小时以内,10,数据I/O平均时间,2周以上,12周,17天,124小时,1小时以内,11,编程语言,高级语言,高级语言带少量的汇编,高级语言带相当多的汇编,汇编语言,机器语言,12,并行软件开发,没有,有限,中等程度,很多,全部,然后，将上表衡量所得的各个因素的值相加，得总和值。再根据下表，确定应编制的文档种类。,可行性研究报告,项目开发计划,软件需求说明书,数据要求说明书,概要设计说明书,详细设计说明书,测试计划,用户手册,操作手册,测试分析报告,开发进度月报,项目开发总结,程序维护手册,1218,*,1626,*,2438,*,3650,*,4860,*,文档的种类,因素值总和,表中：*，表示此文档应编制，但不必太正规；,*，表示应根据所开发软件的实际需要来确定是否需要编制此文档。,（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可选择的系统方案1,5.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图的例，具有可追踪性。,字处理系统,输出,2.0,输入,1.0,存储,4.0,编辑,3.0,格式化,6.0,检索,5.0,编目录,7.0,删除,3.2,添加,3.1,修改,3.4,插入,3.3,列表,3.6,合并,3.5,IPO图使用的符号既少又简单，能够方便的描述数据输入、处理和输出之间的关系。如下图是一个主文档更新的IPO例子。,程序名：,模块名：,编制者：,日 期：,页号：,输入,处理,输出,旧的主文件,事务文件,1.检验主记录,2.校验事务记录,3.更新主记录,有效的主记录,有效的事务记录,更新后的主记录,图中，箭头清楚的指出了数据通信的情况。,结构化表现形式：结构图,Yourdon提出的结构图是进行软件结构设计的另一个有力的表达方法。而且，结构图较之层次图有更强的描述力。,产生最佳解,得到好输入,计算最佳解,输出结果,读输入,编辑输入,结果格式化,显示结果,好输入,解,好输入,解,原始输入,原始输入,编辑结束,解,解的格式化,格式化的解,结构化表现形式：结构图,结构图还有一些附加的符号，用以表示模块的选择调用和循环调用。如下图，左图是选择调用，右图是循环调用。,M,A,B,判定为真时调用模块A，否则调用模块B,M,A,C,B,模块M循环调用模块A、B、C,2、面向对象设计表现形式,（1）面向对象设计(OOD)的 4个部分,这4个部分是问题域、人机交互部分、任务管理部分和数据管理部分。如下图所示。,主题层,类及对象层,结构层,属性层,问题域部分,人机交互部分,任务管理部分,数据管理部分,-,问题域部分,：OOD根据需求分析中对问题域的描述，针对实现要求进行必要的整补和调整。其重点是：重用类设计、组合问题域专用类、调整继承的支持级别、提供数据管理部分以及增加底层细节。,-,人机交互部分设计,：突出人如何命令系统，及系统如何向用户提交信息。尤其对非计算机专业用户如何提交信息。,-,任务管理部分设计,：设计策略要点是识别并设计任务，加上包含在每个任务中的服务。,-,设计管理部分设计,：该部分主要是为了隔离数据管理方案对系统设计表达的影响。设计既包含数据存放方法的设计，也包含相应服务的设计。,继承机制的表示,通常将父类放在上面，将子类放在下面。如左图,A,B,父类,子类,派生 继承,下图是表示鸡、鸭、猫、狗和动物之间的继承关系。,动物,家禽类,宠物,鸡,鸭,鹅,狗,猫,聚集关系的表示,若类B的定义将类A的对象作为数据成员，则B和A之间是一种聚集关系，其表示方法如下图所示。,汽车B,轮胎A,子午线轮胎,对象关联的表示,关联源对象,关联指针,被关联对象,属性,Next,关联对象指针,属性,Next,关联对象指针,属性,Next,关联对象指针,被关联对象,被关联对象,内嵌关联结构表示,外嵌关联结构表示,A类对象：A1,A类对象：A1,A类对象：A2,B类对象：B1,B类对象：B2,B类对象：B3,AB关联类,B类,AB类对象关联表,A类对象标识 B类对象标识 关联对象,A1 B1AB1,A1 B2AB2,A2 B1AB3,结构化表现形式：层次图示例,使文档保持更新，但频度不要过高,GB/T 9386-1988,说明该系统同其他系统之间的接口、数据通信协议等。,图中，箭头清楚的指出了数据通信的情况。,Application,有限的灵活性，允许格式上有些变化,计算机软件需求说明编制指南,日立公司，1973年提出。,列出支持软件，包括要用到的操作系统、编译程序、测试支持软件等。,Split document into single words,代理是一种在应用和被访问对象之间建立的桥梁或关口。,GB/T 12504-1990,注册/观察器的表示,一种将新的信息一对一的迅速传送或通知给相关对象的对象协作机制。特别在分布式环境中，对象通信代价很高时，这是一种高效的手段，在网络软件设计时常用。见下图例。,生产者,Collection Client,Attach(),Detach(),GetData(),Generator(),Notify(),客 户,生产者*Gen,客户(),客户(),Update(),SetGen(),Notify(),Client,Update(),Gen,Attach(),Gen,Detach(),1.n,虚拟设备的表示,虚拟设备是操作系统的一个重要概念。使用这种概念，可以为在不同设备上实现相同功能，或以相同操作接口访问不同设备提供可能和方便。如图,Application,Canvas,Draw(),Line(),Circle(),Rectangle(),TextOut(),DrawSpace,Draw(),Line(),Circle(),Rectangle(),TextOut(),Printer,DrawSpace,Draw(),Line(),Circle(),Rectangle(),TextOut(),PrinterPrew,DrawSpace,Draw(),Line(),Circle(),Rectangle(),TextOut(),ScreenWin,DrawSpace,Draw(),Line(),Circle(),Rectangle(),TextOut(),OtherGDI,代理结构的表示,代理是一种在应用和被访问对象之间建立的桥梁或关口。通过代理的虚拟作用，达到控制对象访问的目的。,代理具有的作用或特性可以包括间接性、委托性、临时替代性、虚拟性、安全性/保护性、远程性和多源性。,下图是代理模式的实现结构表示的例子。,Application,Object,Service(),ActualObject,Service(),Object*anObject,Service(),Proxy,anObject,Return anObject,Service(),网络代理连接的表示例子：,应用,代理,远程对象,多源代理连接的例子,应用,代理问题求解,对象1,对象n,对象2,连接,连接,连接,连接,软件详细设计文档,软件详细设计文档,详细设计在概要设计之后，其工作重点是考虑实现各个模块的规定功能，表达的是模块内部的逻辑关系、数据结构和模块接口细节等，表达的方法主要有程序流程图、N-S图、PAD图、PDL语言以及判定表、树等。,程序流程图,程序流程图(Program Flow Chart)的5种基本控制结构：,(1)顺序结构,(,sequential structure),(2)选择结构,(selective structure),A,B,P,B,A,F,T,(3)先判定型循环结构,(while-loop structure),(4)后判定型循环结构,(until-loop structure),T,P,S,F,F,S,T,P,(5)多情况选择,(case structure),T,A1,F,P=1,T,A2,F,P=2,T,An,F,P=n,N-S图：,顺序,A,B,P,F,T,A,B,选择,P,F,T,B,Do-While P,S,While型循环,Do-Until P,S,Until型循环,Case型选择,P,1,2,n,A1,A2,An,子过程调用,A,设计既包含数据存放方法的设计，也包含相应服务的设计。,软件工程标准编制的层次,说明控制该系统的运行的方法和控制信号，并说明这些控制信号的来源。,该方法的要点是提出12个考虑因素来衡量一个应用软件，以及每个因素可能取值的范围。,PROCEDURE spell_check IS,A1 B2AB2,是软件开发各阶段工作成果的体现；,Rectangle(),ActualObject,是一种非正文形式的过程设计工具。,使文档保持更新，但频度不要过高,PAD图(Problem Analysis Diagram)：,日立公司，1973年提出。为ISO所极力推荐。也有5种基本控制结构。,A,B,顺序,While P,S,Until P,S,循环,P,A,B,THEN,ELSE,选择,P=,A1,A2,Case型选择,An,1,2,n,陈述索引,def,定义,PDL(Program Design Language)：,是一种非正文形式的过程设计工具。,PDL语言的特点：,有,固定的关键字外语法,，有完整的结构化的控制结构、数据说明和模块特征；,内语法使用自然语言描述处理特征,，为使用者提供方便，提高可读性；,有数据说明机制。包括简单的(标量和数组)和复杂的(链表和层次结构)数据结构；,有子程序定义和调用机制，及各种方式的接口说明。,PDL示例,PROCEDURE,spell_check,IS,BEGIN,Split document into single words,Look up words in dictionary,Display words which are not in dictionary,Create a new dictionary,END,spell_check,External,statements,Internal,statements,国标(GB8567-88)关于概要设计和详细设计的模板主要有：,1.概要设计说明书,2.数据库设计说明书,3.组装测试计划,4.详细设计说明书,管理文档,管理文档概述,工程化的软件生产方式是软件业界始终在不懈追求的目标。软件项目管理方法适用与否，对软件项目的成败有着举足轻重的作用。二软件项目管理方法改进的途径之一，就是建立行之有效、可操作性强的软件管理文档。,软件管理文档,项目开发计划,测试计划,测试分析报告,开发进度报告,开发总结报告,管理文档的组成：,管理文档有以下几个方面的作用：,维护人员,软件开发管理人员,软件开发人员,软件操作人员,用户,软件管理文档,管理文档的作用主要体现在3个方面：,是软件开发各阶段工作成果的体现；,把软件开发过程中的一些“不可见”的事物转换成“可见”的文字资料；,提供了管理人员、开发人员、操作人员和用户之间相互沟通、协调的窗口。,多用途、灵活的格式、有主题领域,GB/T 15535-1995(ISO 5806),单机、常规处理、扩充的外设系统,这里，我们把软件的规模分为四级：,然后，把这12个因素的值相加，得到一个总和，就可以根据这个总和的值，来确定应该编制的文档的种类。,PROCEDURE spell_check IS,使用这种概念，可以为在不同设备上实现相同功能，或以相同操作接口访问不同设备提供可能和方便。,待开发的系统的名称；,Rectangle(),软件文档根据其产生和使用的范围，主要划分为3大类：开发文档、用户文档和管理文档。,GB/T 14085-1993(ISO 8790),而且，结构图较之层次图有更强的描述力。,2、面向对象设计表现形式,模块M循环调用模块A、B、C,有固定的关键字外语法，有完整的结构化的控制结构、数据说明和模块特征；,用户文档,用户文档是软件开发人员为软件用户了解、使用、操作和维护等提供的详细资料。,用户文档包括用户手册、操作手册和维护修改建议等。,文档管理,