2022年软件项目文档定义 .pdf

软件文档文档的作用和分类软件文档 (document)也称文件，通常指的是一些记录的数据和数据媒体，它具有固定不变的形式，可被人和计算机阅读。 它和计算机程序共同构成了能完成特定功能的计算机软件(有人把源程序也当作文档的一部分 )。我们知道，硬件产品和产品资料在整个生产过程中都是有形可见的，软件生产则有很大不同，文档本 身就是软件产品。没有文档的软件，不成其为软件，更谈不到软件产品。软件文档的编制(documentation)在软件开发工作中占有突出的地位和相当的工作量。高效率、高质量地开发、分发、管理和维护文档对于转让、变更、修正、扩充和使用文档，对于充分发挥软件产品的效益有着重要意义。然而，在实际工作中，文档在编制和使用中存在着许多问题，有待于解决。软件开发人员中较普遍地存在着对编制文档不感兴趣的现象。从用户方面看，他们又常常抱怨：文档售价太高、文档不够完整、文档编写得不好、文档已经陈旧或是文档太多，难于使用等等。究竟应该怎样要求它，文档应该写哪些，说明什么问题，起什么作用?这里将给出简要的介绍。图 文档桥梁作用文档在软件开发人员、软件管理人员、维护人员、用户以及计算机之间的多种桥梁作用可从图92 中看出。软件开发人员在各个阶段中以文档作为前阶段工作成果的体现和后阶段工作的依据，这个作用是显而易见的。 软件开发过程中软件开发人员需制定一些工作计划或工作报告，这些计划和报告都要提供给管理人员，并得到必要的支持。管理人员则可通过这些文档了解软件开发项目安排、进度、资源使用和成果等。软件开发人员需为用户了解软件的使用、操作和维护提供详细的资料，我们称此为用户文档。以上三种文档构成了软件文档的主要部分。我们把这三种文档所包括的内容列在图6 中。其中列举了十三个文档，这里对它们作一些简要说明：? 可行性研究报告：说明该软件开发项目的实现在技术上、经济上和社会因素上的可行性，评述为了合理地达到开发目标可供选择的各种可能实施的方案，说明并论证所选定实施方案的理由。? 项目开发计划：为软件项目实施方案制定出具体计划，应该包括各部分工作的负责人员、开发的进度、开发经费的预算、所需的硬件及软件资源等。项目开发计划应提供给管理部门，并作为开发阶段评审的参考。? 软件需求说明书：也称软件规格说明书，其中对所开发软件的功能、性能、用户界面及运行环境等作出详细的说明。它是用户与开发人员双方对软件需求取得共同理解基础上达成的协议，也是实施开发工作的基础。? 数据要求说明书：该说明书应给出数据逻辑描述和数据采集的各项要求，为生成和维护系统数据文卷作好准备。名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 1 页，共 14 页 - - - - - - - - - ? 概要设计说明书：该说明书是概要设计阶段的工作成果，它应说明功能分配、模块划分、程序的总体结构、输入输出以及接口设计、运行设计、数据结构设计和出错处理设计等，为详细设计奠定基础。? 详细设计说明书：着重描述每一模块是怎样实现的，包括实现算法、逻辑流程等。?用户手册：本手册详细描述软件的功能、性能和用户界面，使用户了解如何使用该软件。文档用户文档用户手册操作手册维护修改建议软件需求（规格）说明书开发文档软件需求（规格）说明书数据要求说明书概要设计说明书详细设计说明书可行性研究报告项目开发计划管理文档项目开发计划测试计划测试报告开发进度月报开发总结报告?图 三种文档? 操作手册：本手册为操作人员提供该软件各种运行情况的有关知识，特别是操作方法的具体细节。? 测试计划：为做好组装测试和确认测试，需为如何组织测试制定实施计划。计划应包括测试的内容、进度、条件、人员、测试用例的选取原则、测试结果允许的偏差范围等。? 测试分析报告：测试工作完成以后，应提交测试计划执行情况的说明。对测试结果加以分析，并提出测试的结论意见。? 开发进度月报：该月报系软件人员按月向管理部门提交的项目进展情况报告。报告应包括进度计划与实际执行情况的比较、阶段成果、遇到的问题和解决的办法以及下个月的打算等。名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 2 页，共 14 页 - - - - - - - - - ? 项目开发总结报告：软件项目开发完成以后，应与项目实施计划对照，总结实际执行的情况，如进度、成果、资源利用、成本和投入的人力。此外还需对开发工作作出评价，总结出经验和教训。? 维护修改建议，软件产品投入运行以后，发现了需对其进行修正、更改等问题，应将存在的问题、修改的考虑以及修改的影响估计作详细的描述，写成维护修改建议，提交审批。以上这些文档是在软件生存期中，随着各阶段工作的开展适时编制。其中有的仅反映一个阶段的工作，有的则需跨越多个阶段。表5 给出了各个文档应在软件生存期中哪个阶段编写。这些文档最终要向软件管理部门，或是向用户回答以下的问题：表 9.2 软件生存期各阶段编制的文档阶段文档可行性药酒与计划需求分析 设计 代码编写 测试 运行与维护可行性研究报告项目开发计划软件需求说明数据要求说明概要设计说明星系设计说明测试计划用户手册操作手册测试分析报告开发进度月报项目开发总结维护修改建议? 哪些需求要被满足，即回答“做什么?”? 所开发的软件在什么环境中实现以及所需信息从哪里来，即回答“从何处?”? 某些开发工作的时间如何安排，即回答“何时干?”? 某些开发 (或维护 )工作打算由“谁来干?”? 某些需求是怎么实现的? ? 为什么要进行那些软件开发或维护修改工作? 上述十三个文档都在一定程度上回答了这六个方面的问题。这可从表中看到。表 文档所回答的问题名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 3 页，共 14 页 - - - - - - - - - 所提问题文档什么何处何时谁如何为何可行性研究报告项目开发计划软件需求说明数据要求说明概要设计说明详细设计说明测试计划用户手册操作手册测试分析报告开发进度月报项目开发总结维护修改建议至此，我们对文档的作用有了进一步的理解。每一个文档的任务也是明确的， 任何一个文档都此是多余的。文档的管理和维护在整个软件生存期中，各种文档作为半成品或是最终成品，会不断地生成、修改或补充。为了最终得到高质量的产品，达到上节提出的质量要求，必须加强对文档的管理。以下几个方面是应注意做到的：软件开发小组应设一位文档保管人员，负责集中保管本项目已有文档的两套主文本。两套文本内容完全一致。其中的一套可按一定手续，办理借阅。软件开发小组的成员可根据工作需要在自己手中保存一些个人文档。这些一般都应是主文本的复制件，并注意和主文本保持一致，在作必要的修改时，也应先修改主文本。开发人员个人只保存着主文本中与他工作相关的部分文档。在新文档取代了旧文档时，管理人员应及时注销旧文档。在文档内容有更动时，管理人员应随时修订主文本，使其及时反映更新了的内容。项目开发结束时，文档管理人员应收回开发人员的个人文档。发现个人文档与主文本有差别时，应立即着手解决。这常常是未及时修订主文本造成的。在软件开发过程中，可能发现需要修改已完成的文档，特别是规模较大的项目，主文本的修改必须特别名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 4 页，共 14 页 - - - - - - - - - 谨慎。修改以前要充分估计修改可能带来的影响，并且要按照：提议、评议、审核、批准和实施等步骤加以严格的控制。文档编制的质量要求为了使软件文档能起到前节所提到的多种桥梁作用，使它有助于程序员编制程序，有助于管理人员监督和管理软件开发，有助于用户了解软件的工作和应做的操作，有助于维护人员进行有效的修改和扩充，文档的编制必须保证一定的质量。质量差的软件文档不仅使读者难于理解，给使用者造成许多不便，而且会削弱对软件的管理 (管理人员难以确认和评价开发工作的进展)，增高软件的成本 (一些工作可能被迫返工)，甚至造成更加有害的后果(如误操作等 )。造成软件文档质量不高的原因可能是：?缺乏实践经验，缺乏评价文档质量的标准。?不重视文档编写工作或是对文档编写工作的安排不恰当。最常见到的情况是，软件开发过程中不能按表5 给出的进度，分阶段及 ?时完成文档的编制工作，而是在开发工作接近完成时集中人力和时间专门编写文档。另一方面，和程序工作相比，许多人对编制文档不感兴趣。于是在程序工作完成以后，不得不应付一下，把要求提供的文档赶写出来。这样的做法不可能得到高质量的文档。实际上，要得到真正高质量的文档并不容易，除去应在认识上对文档工作给予足够的重视外，常常需要经过编写初稿，听取意见进行修改，甚至要经过重新改写的过程。高质量的文档应当体现在以下一些方面：针对性；文档编制以前应分清读者对象，按不同的类型、不同层次的读者，决定怎样适应他们的需要。例如，管理文档主要是面向管理人员的，用户文档主要是面向用户的，这两类文档不应像开发文档 (面向软件开发人员 )那样过多地使用软件的专业术语。精确性：文档的行文应当十分确切，不能出现多义性的描述。同一课题若干文档内容应该协调一致，应是没矛盾的。清晰性：文档编写应力求简明，如有可能，配以适当的图表，以增强其清晰性。完整性：任何一个文档都应当是完整的、独立的，它应自成体系。例如，前言部分应作一般性介绍，正文给出中心内容，必要时还有附录，列出参考资料等。同一课题的几个文档之间可能有些部分相同，这些重复是必要的。例如，同一项目的用户手册和操作手册中关于本项目功能、性能、实现环境等方面的描述是没有差别的。特别要避免在文档中出现转引其它文档内容的情况。比如，一些段落并未具体描述，而用“见文档节”的方式，这将给读者带来许多不便。灵活性：各个不同的软件项目，其规模和复杂程度有着许多实际差别，不能一律看待。图6 所列文档是针对中等规模的软件而言的。对于较小的或比较简单的项目，可做适当调整或合并。比如，可将用户手册和操作手册合并成用户操作手册；软件需求说明书可包括对数据的要求，从而去掉数据要求说明书；概名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 5 页，共 14 页 - - - - - - - - - 要设 计说明书与详细设计说明书合并成软件设计说明书等。可追溯性； 由于各开发阶段编制的文档与各阶段完成的工作有着紧密的关系， 前后两个阶段生成的文档，随着开发工作的逐步扩展，具有一定的继承关系。在一个项目各开发阶段之间提供的文档必定存在着可追溯的关系。例如，某一项软件需求，必定在设计说明书，测试计划以至用户手册中有所体现。必要时应能做到跟踪追查。程序文档合一与动态文档很多企业已经建立了许多庞大的计算机管理系统，而且将不断地推出新的系统。满足经营的需求须不断维护、改造计算机系统，但同时又要不影响现行生产，所以必须建立一整套机制来评价、控制和完成对系统的维护。在软件维护过程中，提出程序与文档合一的概念在软件开发的同时建立动态文档。程序与文档合一概念的提出一、目前软件的状况程序与文档的形式分离，不仅是用各自独立的形式存放，而且使用不同的工具在不同的时间里书写和检索。维护程序时不能方便地得到文档的帮助，不能同步修改文档。程序与文档的内容分离，由于程序与文档采用不同的描述，既有计算机语言也有自然语言。维护过程中不能及时、一致地更新文档或程序，使文档不能准确地描述程序而几乎成为废纸甚至带来负面价值。软件开发与维护的分离，绝大多数软件在设计、开发时不太考虑以后可能的修改，加大了软件维护的难度，而且使维护容易引入新的错误。这些分离也表现在设计、开发的不同阶段的文档之间的不相容性，例如：需求分析说明书是纸上的东西，在概要设计阶段不能很好地继承、利用需求分析说明书，设计、编制概要设计时必须从零开始，需要重新分析、理解需求分析，这种思维上的脱节，不仅延缓开发进度、加重设计人员的负担，而且由于理解上的不同导致不同阶段描述的对象有许多不相容情况。这些分离使得文档在系统的设计、开发、维护中的作用下降，这也是很多软件人员不愿意编写文档的主要原因。二、程序与文档合一的概念提出怎样才是好的文档系统呢？应当具备以下属性：1. 能够准确地描述软件、并且简单易懂；2. 能够迅速错误定位、影响分析、修正设计；3. 能够提高软件维护质量；4. 能够方便程序修改时理解程序。为此提出了程序与文档合一的概念。这概念使软件成为真正意义上的软件：程序 +文档，程序就是文档，文档集成在程序中。它要求在选择开发环境时不仅要考虑环境对设计、开发的完美支持，而且要考虑对维护、文档的支持；它要求软件人员在设计、开发过程中要考虑维护问题、文档问题；它要求程序与文档存名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 6 页，共 14 页 - - - - - - - - - 储在同一位置、同一系统中；它要求使用相同工具进行程序与文档的书写、检索；它要求在编写和维护程序的同时形成文档，在书写文档时编写、维护程序。程序与文档合一的概念不仅存在于系统的设计、开发阶段而且存在于系统的维护阶段，它贯穿软件的生命周期。动态文档系统是建立在程序与文档合一的概念基础上的、文档与程序一致的、简单易懂的联机文档系统。它包括构件说明与数据描述、对构件与构件之间、构件与数据之间的关系进行的描述。动态文档系统是提高了文档的可用性、易用性和连贯性，使文档更加有效，是解决维护问题的有效途径。动态文档系统问题分析需要解决的问题是：软件文档的内容划分与获取、文档的存储与维护、文档的检索、软件文档的生成打印。一、软件文档的内容划分成：语义文档、结构文档、过程文档语义文档是对软件的功能、概念、总体设计、流程、规约等用自然语言的描述，是软件人员根据规范在使用 CASE 工具编写并填入程序的文档，它也是为更全面的解释文档而灵活加入的额外信息。结构文档是在软件设计工具、开发环境中对象的属性、构件间接口、构件间引用关系、软件的结构等的描述。利用词法、语法分析程序对整个系统的对象、构件进行识别、分析，获取上述描述并形成表格文件。过程文档是对软件的设计、编码、维护过程中形成的过程描述和程序注释，如设计目的、设计人、时间等说明，利用开发环境对软件人员在设计、开发、维护过程中操作的记录形成操作跟踪。二、程序与文档的统一存储与维护根据程序与文档合一的概念和文档从程序中提取的要求，文档必须存放在程序中，甚至文档固有的源代码中。结构如此的程序源代码的存储必须采用一种新技术对象仓储（Repository ）技术，而不能采用流式文件，这样才能使程序与文档既结合又分离。程序与文档结合在一个对象仓储中，结合在统一的开发环境中；结合在修改代码时可以同时修改文档、修改文档时可以同时人工检查和修改程序，并在多次文档生成而不会丢失手工输入的文档。程序与文档应当分别存放在对象仓储中的不同表或不同的字段中，在编译与运行时分离。三、文档的检索对单个对象、构件文档的检索方式是若于文档存放在一个对象仓储中，它可以随源代码一起检索和维护。这种检索给分析和维护单个构件、对象提供文档支持。建立多种视图、编写程序对整个系统进行文档的检索和获取，完成对整个系统的分析，对整个系统进行实时文档支持。这将在例子中较详细的描述。四、软件文档的生成打印编写程序检索和获取整个系统的文档，按照国家软件标准的文档式样建立文档模板并将按模板生成文档和利用文字处理软件强大的功能进行创建、编辑文档并打印。根据上述分析，文档分布和获取对开发环境提出了要求：开发环境应该是设计工具、开发工具的集成，名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 7 页，共 14 页 - - - - - - - - - 应该基于 CASE 技术、对象仓储技术、构件技术、OLE 技术。基于CASE 技术的开发环境；设计、开发、维护过程中形成的文档并植入程序代码中，使文档成为程序的一部分。基于对象仓储技术的开发环境，将文档与程序统一存储在对象仓储中方便检索。基于构件技术的开发环境，便于识别、获取构件，分析、形成结构文档和过程文档。基于OLE 等技术使文档可以很好地利用Word 等文档处理软件。动态文档系统的一个应用实例广州电信科技开发有限公司自行设计、开发的名为九七系统的庞大的电信管理计算机系统自1997 年投产验收后，将长期用于生产，维护工作非常重要和紧迫。这为动态文档系统提供了需求和试验场所。在长期维护的过程中，体会到好文档的重要性并提出了程序文档合一的概念，这为动态文档系统提供了理论基础。九七系统是使用Uniface 开发环境。这种开发环境采用了CASE 技术、对象仓储技术、构件技术，这为动态文档系统提供了技术支撑。一、广州电信动态文档系统的建立步骤1. 理解 Uniface、Oracle 工具的开发环境，规划语义文档在各级对象中存放的表与字段，并根据工具的特性制定填写的规则。2. 寻找结构文档、过程文档在Uniface、Oracle 工具中存放的表与字段。3. 在设计、开发和维护软件的过程中对这些表或字段按照规则进行填写。4. 建立一整套模板使文档结构与信息源建立映像，包括：数据字典模板、设计文档模板、结构文档模板、开发过程文档模板等。5. 将这些模板组装成文档系统，并使它独立于开发目标系统。广州电信动态文档系统的组成可以分为文档查询、维护记录查询、文档生成。文档查询不仅包括构件说明与数据描述，而且包括对构件与数据之间的关系的描述，是实时的联机文档查询系统。维护记录查询是对软件维护过程中的各个环节进程进行记录与追踪，用于规范维护工作。它包括问题报告、问题分析、错误定位、维护设计、维护执行、确认测试、维护评审、维护提交、问题跟踪等。文档生成则是根据需要实时生成软件设计说明书。二、程序与文档合一概念与动态文档系统的意义广州电信动态文档系统的基本任务是辅助错误定位、维护影响分析、记录维护进程、生成文档。使用Uniface 的开发环境开发的，可以安装在用Uniface 开发的不同的应用系统中。该系统已经在九七计费系统的维护中发挥重要作用。它推崇的程序与文档合一的概念，提出文档就是程序，程序就是文档的思路，文档融合在程序中的构思并已实现，这一概念指导了软件人员进行有效地工作。合一的概念贯穿了设计、开发、维护整个软件周期，保证了文档之间的继承性和一致性，在设计、开发每一阶段是继承前阶段的程序和文档的结果。这样极大地消除了程序与文档、文档与文档之间的不一致性，加快了软件设计进度，提高了软件开发、维护的质量。它是软件工程在具体应用中的一种尝试，它从程序文档合一的角度出发，进一步规范软件设计、开名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 8 页，共 14 页 - - - - - - - - - 发、维护。程序文档合一的概念为软件开发环境发展提供了一种思路；设计更好的对象仓储来满足开发、维护人员对程序文档合一的概念的需求。动态文档系统的局限与发展广州电信动态文档系统有很大的局限性，只能用于Uniface 或 Oracle 开发的系统中。目前的广州电信动态文档系统的构件的识别与获取主要依赖开发工具提供的构件和构件的特征进行识别的。这种动态文档系统难以在一些3GL 工具未使用对象仓储技术、构件技术开发的软件中实现程序与文档的合一与分离。大型软件系统的环境是复杂的，往往采用了多种开发环境，如何对其他开发环境进行支持还要进行技术探讨和实践上的摸索。另一个局限问题是目前的动态文档系统描述的是程序文档，其主要在编码、维护的过程中进行建设，系统进入维护阶段使用。如何使动态文档系统不仅对软件维护阶段进行支持，而且对软件的设计、开发阶段进行更多的支持？一种可能的解决途径是将软件复用技术拓宽到包括文档复用，包括程序复用、程序文档复用和设计文档复用，而且将动态文档系统建立在基于这种软件复用系统之上。如何编写高质量“软件需求说明书”你的工程应该有个好的起点。一个小组要带领客户进入需求启发阶段而且你要写软件需求说明书。这份说明有些大，但客户会很重视，所以说明必须得到赞同。现在你正在设计其中的一个特性，已经发现了需求的一些问题。你可以用多种不同的方式解释需求15；需求 9 的说明正好与需求21 相反，你因该相信哪一个？需求24 非常含糊，你根本不明白它的意思；你不得不花上一个小时与2 位开发人员讨论需求30，只因为你们对其各有各的理解；并且，唯一能够澄清这些问题的客户没有给你们答复。你被迫破解众多需求的含义，并且你能预料到，如果你错了，你要做大量的重复工作。许多软件需求说明书（SRS ）写得非常糟糕。任何产品的质量需要其原始材料的质量保证，糟糕的软件需求说明书不可能产出优秀的软件。不幸的是，几乎没有开发人员受过与需求的抽象、分析、文档、质检有关的教育。而且，没有非常多的好需求可以借鉴学习，部分原因是很少有工程可以找到一个好的借鉴，其他原因是公司不愿意将其产品说明书放在公共区域。这篇文章描述了高质量需求叙述和说明的几个特性（特点）。我们将用这些观点检查一些有缺陷的需求，带着痛楚重新编写。而且我会谈一些如何编写好的需求的提示。你也许想通过这些质量标准评估你的工程需求。对于修订，也许迟了，但你会学到一些有用的东西，并帮助你的小组在下次编写出更好的需求。不要期望能够编写出一份能体现需求应具备的所有特性的SRS。无论你怎么细化、分析、评论和优化需求，都不可能达到完美。但是，如果你牢记这些特性，你就会编写出更好的需求，生产出更好的产品。高质量需求叙述的特性名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 9 页，共 14 页 - - - - - - - - - 我们如何从一些有问题的需求中分辨出好的软件需求？这一节将分别介绍需求叙述应体现的6 个特性，下一节将从整体上介绍SRS文档应具备的特性。判断每个需求是否具备应有的特性的一种方式是由持有不同观点的工程资金管理人所作的正规检查。另一种有力的方法是在编写代码前依据需求编写测试例子。测试例子能够明确显现在需求中描述的产品行为（特性），能够显现缺陷、冗余和含糊之处。正确：每个需求必须精确描述要交付的功能。正确性依据于需求的来源，如真实的客户或高级别的系统需求说明书。一个软件需求与其对应的系统需求说明书相抵触是不正确的（当然，系统需求说明书本身可能不正确）。只有用户的代表能够决定用户需求的正确性，这就是为什么在检查需求时，要包括他们或他们的代理的关键所在。不包括用户的需求检查就会导致开发人员的：“这是没意义的”，“这可能是他们的意思”等众所周知的猜测。可行性：在已知的能力、有限的系统及其环境中每个需求必须是可实现的。为了避免需求的不可行性，在需求分析阶段应该有一个开发人员参与，在抽象阶段应该有市场人员参与。这个开发人员应能检查在技术上什么能做什么不能做，哪些需要需要额外的付出或者和其他的权衡。必要性：每个需求应载明什么是客户确实需要的，什么要顺应于外部的需求，接口或标准。每个需求源于你认可、具有权说明需求的原始资料，这是考虑必需的另外情形（译注，此句翻译不顺，请参照原文：Another way to think of “necessary ” is that each requirement originated from a source you recognize as having the authority to specify requirements）。跟踪每个需求回溯到出处，如用例，系统需求，规章，或来自其他用户的意见。如果你不能标识出处，可能需求只是个镀金的例子，没有真正的必须。优先权：为了表明在一个详细的产品版本中应包含哪些要点，需要为每个需求，特征，或用例分配实现的优先权。客户或其代理都应有强烈的责任建立优先权。如果所有的需求都被视为同等重要，那么由于在开发中，预算削减，计划超时或组员的离开导致新的需求时，项目经理将不能起到作用。优先权的作用是提供给客户的价值，实现的相关费用，实现相关联的有关技术风险。我是用 3 种级别的优先权：高优先权表明需求必须体现在下一个产品版本中，中优先权表明需求是必须的，但是如果需要可以推迟到晚一些的产品版本中，低优先权表明有它很好，但我们必须认识到如果没有充足的时间或资源，它可以被放弃掉。明确：需求叙述的读者应只能从其得到唯一的解释说明，同样，一个需求的多个读者也应达成共识。自然语言极易导致含糊。要避免使用一些对于SRS作者很清楚但对于读者不清楚的主观词汇，如：用户友好性，容易，简单，快速，有效，几个，艺术级，改善的，最大，最小等等。每写一个需要都应简洁，简单，直观的采用用户熟知的语言，不要采用计算机术语。检查需求模糊的有效方式包括需求说明书的正规检查，根据需求写测试，建立用户的假想来说明产品某个特定部分预期的特性。可证实：看你是否能够做出测试计划或其他验证方式，如检查和实证，来决定在产品中每个需求是否正确的实现。如果需求是不可验证的，决定需求是不是正确的实现就成了判断的事。需求之间不一致，不名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 10 页，共 14 页 - - - - - - - - - 可行，不明确也能导致不可证实。任何需求如果说产品将要支持什么也是不可证实的。高质量需求说明的特征一个完整的SRS不仅是包括长长的功能性需求列表，还包括外部接口描述和一些诸如质量属性，期望性能的非功能性需求。下面描述了高质量的SRS的一些特性。完整：不应该遗漏要求和必需的信息。完整性也是一个需求应具备的。发现缺少的信息很难，因为根本不存在。在SRS中将需求以分层目录方式组织，将帮助评审人员理解功能性描述的结构，使他们很容易指出遗失的东西。在需求抽象时，相对于系统功能，你过多的注意用户的业务，将导致在需求的全局观和引进不是真正必需的需求上显得不足。在需求抽象上，应用用例方法会发挥很好的作用。能够从不同角度察看需求的图形分析模型也可以检查出不完整性。如果你知道已缺少一些信息，使用TBD （to be determined）标准标志可以突出这些缺陷，当你在构建产品的相关部分时，就可以从一个给定的需求集中解决所有的缺陷。一致性：一致性需求就是不要于其他的软件需求或高级别的系统（商业）需求发生冲突。需求中的不一致必须在开发开始前得到解决。只有经过调研才能确定哪些是正确的。修改需求时一定要谨慎，如果只审定修改的部分，没有审定于修改相关的部分，就可能导致不一致性。可修改性：当每个需求的要求修改了或维护其历史更改时，你必须能够审定SRS。也就是说每个需求必须相对于其他需求有其单独的标示和分开的说明，便于清晰的查阅。通过良好的组织可以使需求易于修改，如：将相关的需求分组，建立目录表，索引，以及前后参考（照）。可追踪：你应能将一个软件与其原始材料相对应，如高级系统需求，用例，用户的提议等。也能够将软件需求与设计元素，源代码，用于构造实现和验证需求的测试相对应。可追踪的需求应该具有独立标示，细密和结构化的编写，不应过大，不应是叙述性的文字和公告式的列表。需求质量的评审这些有关需求质量的特性的描述在理论上都是非常好的，但一个好的需求到底是个什么样子的呢？为了体现得更切合实际，我们做个小练习。下面有几个从实际的工程选出的需求，依据上面的质量标准，评估每个需求，看看有什么问题，然后用更好的方式重写。我将对每个例子都提出自己的分析和改进的建议。也欢迎你提出不同的见解。我所占优的只是我知道每个需求的出处。因为你我都不是真正的客户，我们只能猜测每个需求的意图。例 1“产品应在不少于每60 秒的正常周期内提供状态信息”这个需求是不完整的：状态信息是什么，如何显示给用户。这个需求有几处含糊。我们在谈论产品的哪部分？状态信息间隔真的假定为不少于60 秒？，甚者每10 年显示一条新的状态信息也可以？也许它的意图是消息间隔不应超过60 秒，那么 1 毫秒是不是太短？“每”这个词导致了不确定性。问题的后果，就是需求的不可证实。名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 11 页，共 14 页 - - - - - - - - - 弥补缺陷，重写需求的一种方法：1、状态信息11 后台任务管理器因该以误差上下不超过10 秒的 60 秒间隔，在用户界面的指定位置显示状态信息12 如果后台进程处理正常，那么应该显示任务已完成的百分数/比13 任务完成时，应显示相关的信息14 后台任务出错应该显示错误信息为了分别测试和追踪，我将其分成了多个需求。如果将几个需求串接在一节中，在构造和测试时就很容易漏掉一个。例 2“产品应瞬间在显示和隐藏不可打印字符间切换”计算机在瞬间不能做任何事，所以这个需求不切实可行。它的不完整性表现在没有声明触发状态切换的条件。软件要在某些条件下更改自己？或者用户为了模仿更改要做一些动作？而且，在文档中改变显示的范围是多大：选中的文本，整个的文档，或其他的？这也是个模糊的问题。不可打印字符合隐藏字符一样吗？或者是一些属性标志或一些控制字符？问题的后果，就是需求的不可证实。象这样编写需求也许更好一些：“用户能够在一个由特定触发条件激活处于编辑的文档中在显示和隐藏所有 HTML 标记间切换”。现在就很清楚，不可打印字符是HTML 标记。由于没有定义触发条件，需求对设计没有约束力。只有设计人员选定了触发条件后，你才能编写测试验证触发的正确操作。例 3“HTML分析器可以产生HTML标记错误报告，帮助HTML 入门者快速解决错误”。单词“快速”使其模糊，没有加进错误报告的定义也是其部完整。我不知道，你怎么验证这个需求。找一个自称为 HTML的入门者，看看能不能根据错误报告快速解决错误？试试这个： “HTML 分析器可以产生一个错误报告，错误报告包含有在被分析文件中出错的HTML 文本和行号以及错误的描述。如果没有错误，就不会产生错误报告”。现在我们知道了，什么会被加到出错报告中，但是出错报告是个什么样子，则留由设计人员决定。我们还指定了一个例外：如果没有发现错误，不产生错误报告。例 4“如果可能，主管号码应通过联机校验，而不是通过主全体主管号码列表校验”。真感到绝望，什么是“如果可能”：如果技术上可行？如果主全体主管号码列表可以联机获得？要避免象“应该”的这类不确切的词。客户是需要这个功能性还是不需要。我曾看过一些需求说明书，采用诸如：应，将，应该/将要等一些词描述优先级的细微差别。但我更喜欢用“应”清楚的说明需求的意图，指明优先级。这是修改后的：系统应校验输入的主管号码而不通过联机的主全体主官号码列表。如果在列表中没有发现主管号码，将会显示一条错误信息，也不接受指令。在理解各个已完成的糟糕需求上，开发人员将会遇到的难题是：开发人员与客户将会在审核需求，未达成共识前发生激烈的争论。详细检查大的需求文档不是一件轻松的事情。我清楚有人做过，而且他们花在检查上的每一分钟都是值得的。相对于开发阶段和用户的抱怨电话，在这个阶段修补缺陷是便宜的，名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 12 页，共 14 页 - - - - - - - - - 编写质量需求的方针编写优秀的需求是没有公式化的方法的。这需要大量的经验，要从你在过去的文档中发现的问题学习。请在组织软件需求文档时，严格遵从这些方针。句子和段落要短。采用主动语气。使用正确的语法，拼写，标点。使用术语，要保持一致性，并在术语表或数据字典中定义它们要看需求是否被有效的定义，可以以开发人员的观点看看。在内心将“当你们做完了找我”这句加到文档尾部，看看能不能是你紧张起来。换句话说，你是否需要SRS的编写者的额外解释帮助开发人员很好的理解需求，以便于设计和实现？如果是的话，在继续工作前，需求还需要细化。需求编写者还要努力正确地把握细化程度。要避免包含多个需求的长的叙述段落。有帮助的提示是编写独立的可测试的需求。如果你认为一小部分测试可以验证一个需求的正确，那么它已经正确的细化了。如果你预想到多种不同类的测试，几个需求可能已挤到了一起，需要拆分开。密切关注多个需求合成了单个需求。一个需求中的连接词“和”/“或”建议几个需求合并。不要在一个需求中使用“和”/“或”。通篇文档细节上要保持一致。我曾看见过多个需求说明书前后不一致。如：“对于红色合法的颜色代码应是 R”及“对于绿色合法的颜色代码应是G”就有可以以分散的需求分离开，而“产品应能对来自语音编辑指示做出反应”应作为一个子系统，不应作为单个的功能性需求。避免在 SRS中过多的申述需求。在多处包含相同的需求可以使文档更易于阅读，但也会给文档的维护增加困难。文档的多份文本要在同一时间内全部更新，避免不一致性。如果你遵从了这些方针，你能够尽早地经常正式或非正式的审查需求，这些需求对于产品的构造，系统测试以及最后的客户满意，都会成为好的奠基石。并且要记住，没有高质量的需求，软件就象一盒巧克力，你永远不知道你会得到什么。国家标准局在 1988 年 1 月发布了计算机软件开发规范和软件产品开发文件编制指南 ，作为软件开发人员工作的准则和规程。它们基于软件生存期方法，把软件产品从形成概念开始，经过开发、使用和不断增补修订，直到最后被淘汰的整个过程应提交的文档归纳为以下 13 种。下面对每种文档的编制做一些简要的说明。 (1) 可行性研究报告：说明该软件开发项目的实现在技术上、经济上和社会因素上的可行性，评述为了合理地达到开发目标可供选择的各种可能实施的方案，说明并论证所选定实施方案的理由。 (2) 项目开发计划：为软件项目实施方案制定出具体计划，应该包括各部分工作的负责人员、开发的进度、开发经费的预算、所需的硬件及软件资源等。项目开发计划应提供给管理部门，并作为开发阶段评审的参考。名师资料总结 - - -精品资料欢迎下载 - - - - - - - - - - - - - - - - - - 名师精心整理 - - - - - - - 第 13 页，共 14 页 - - - - - - - - - (3) 软件需求说明书：也称软件规格说明书，其中对所开发软件的功能、性能、用户界面及运行环境等做出详细的说明。它是用户与开发人员双方对软件需求取得共同理解基础上达成的协议，也是实施开发工作的基础。 (4) 数据要求说明书：应给出数据逻辑描述和数据采集的各项要求，为生成和维护系统数据文卷做好准备。 (5) 概要设计说明书：是概要设计阶段的工作成果，应说明功能分配、模块划分、程序的总体结构、输入输出以及接口设计、运行设计、数据结构设计和出错处理设计等，为详细设计奠定基础。 (6) 详细设计说明书：着重描述每一模块是怎样实现的，包括实现算法、逻辑流程等。 (7) 用户手册：详细描述软件的功能、性能和用户界面，使用户了解如何使用该软件。 (8) 操作手册：为操作人员提供该软件各种运行情况的有关知识，特别是操作方法的具体细节。 (9) 测试计划：为做好组装测试和确认测试，需为如何组织测