软件项目文档

《软件项目文档》由会员分享，可在线阅读，更多相关《软件项目文档（11页珍藏版）》请在金锄头文库上搜索。

1、软件项目文档文档的治理和爱护在整个软件生存期中，各种文档作为半成品或是最终成品， 会不断地生成、修改或补充。为了最终得到高质量的产品，达到上节提出的质量要求，必须加强对文档的治理。以下几个方面是应注意做到的: 软件开发小组应设一位文档保管人员，负责集中保管本项目已有文档的两套主文本。两套文本内容完全 一致。其中的一套可按一定手续，办理借阅。 软件开发小组的成员可依照工作需要在自己手中储存一些个人文档。这些一样都应是主文本的复制件， 并注意和主文本保持一致，在作必要的修改时，也应先修改主文本。 开发人员个人只储存着主文本中与他工作相关的部分文档。 在新文档取代了旧文档时，治理人员应及时注销旧文档

2、。在文档内容有更动时，治理人员应随时修订主 文本，使其及时反映更新了的内容。 项目开发终止时，文档治理人员应收回开发人员的个人文档。发觉个人文档与主文本有差别时，应赶忙 着手解决。这常常是未及时修订主文本造成的。 在软件开发过程中，可能发觉需要修改已完成的文档，专门是规模较大的项目，主文本的修改必须专门 慎重。修改往常要充分估量修改可能带来的阻碍，同时要按照:提议、评议、审核、批准和实施等步骤加 以严格的操纵。文档编制的质量要求为了使软件文档能起到前节所提到的多种桥梁作用，使它有 助于程序员编制程序，有助于治理人员监督和 治理软件开发，有助 于用户了解软件的工作和应做的操作，有助于爱护人员进行

3、有效 的修改和扩充，文 档的编制必须保证一定的质量。质量差的软件文 档不仅使读者难于明白得，给使用者造成许多不便，而且 会削弱对 软件的治理（治理人员难以确认和评判开发工作的进展），增高软 件的成本（一些工作可能被迫返 工），甚至造成更加有害的后果（如误操作等）。造成软件文档质量不高的缘故可能是:缺乏实践体会，缺乏评判文档质量的标准。不重视文档编写工作或是对文档编写工作的安排不恰当。最常见到的情形是，软件开发过程中不能按表5给出的进度，分时期及时完成文档的编制工作，而是在 开发工作接近完成时集 中人力和时刻专门编写文档。另一方面，和程序工作相比，许多 人对编制文档不 感爱好。因此在程序工作完成

4、以后，不得不应对一下，把要求提供的文档赶写出来。如此的做法不可能得 到高质 量的文档。实际上，要得到真正高质量的文档并不容易，除去应在 认识上对文档工作给予足够的 重视外，常常需要通过编写初稿， 听取意见进行修改，甚至要通过重新改写的过程。高质量的文档应当表达在以下一些方面: 针对性；文档编制往常应分清读者对象，按不同的类型、不同层次的读者，决定如何样适应他们的需要。 例如，治理文档要紧是 面向治理人员的，用户文档要紧是面向用户的，这两类文档不应 像开发文档（面向 软件开发人员）那样过多地使用软件的专业术语。 精确性：文档的行文应当十分确切，不能显现多义性的描述。同一课题若干文档内容应该和谐一

5、致，应 是没矛盾的。清晰性：文档编写应力求简明，如有可能，配以适当的图表，以增强其清晰性。 完整性：任何一个文档都应当是完整的、独立的，它应自成体系。例如，前言部分应作一样性介绍，正 文给出中心内容，必要 时还有附录，列出参考资料等。同一课题的几个文档之间可能有些 部分相同，这 些重复是必要的。例如，同一项目的用户手册和操作 手册中关于本项目功能、性能、实现环境等方面的描 述是没有差别 的。专门要幸免在文档中显现转引其它文档内容的情形。比如，一 些段落并未具体描述， 而用“见XX文档XX节”的方式，这将给 读者带来许多不便。 灵活性：各个不同的软件项目，其规模和复杂程度有着许多实际差别，不能一

6、律看待。图6所列文档是 针对中等规模 的软件而言的。关于较小的或比较简单的项目，可做适当调整或合 并。比如，可将用户手 册和操作手册合并成用户操作手册；软件需 求说明书可包括对数据的要求，从而去掉数据要求说明书；概 要设 计说明书与详细设计说明书合并成软件设计说明书等。 可追溯性；由于各开发时期编制的文档与各时期完成的工作有着紧密的关系，前后两个时期生成的文档， 随着开发工作的逐 步扩展，具有一定的继承关系。在一个项目各开发时期之间提供的 文档必定存在着可 追溯的关系。例如，某一项软件需求，必定在设 计说明书，测试打算以至用户手册中有所表达。必要时应 能做到 跟踪追查。程序文档合一与动态文档专

7、门多企业差不多建立了许多庞大的运算机治理系统，而且将不断地推出新的系统。满足经营的需求须不 断爱护、改造运算机系统，但同时又要不阻碍现行生产，因此必须建立一整套机制来评判、操纵和完成对 系统的爱护。在软件爱护过程中，提出程序与文档合一的概念在软件开发的同时建立动态文档。程序与文档合一概念的提出一、目前软件的状况 程序与文档的形式分离，不仅是用各自独立的形式存放，而且使用不同的工具在不同的时刻里书写和 检索。爱护程序时不能方便地得到文档的关心，不能同步修改文档。程序与文档的内容分离，由于程序与文档采纳不同的描述，既有运算机语言也有自然语言。爱护过程 中不能及时、一致地更新文档或程序，使文档不能准

8、确地描述程序而几乎成为废纸甚至带来负面价值。软件开发与爱护的分离，绝大多数软件在设计、开发时不太考虑以后可能的修改，加大了软件爱护的 难度，而且使爱护容易引入新的错误。这些分离也表现在设计、开发的不同时期的文档之间的不相容性，例如：需求分析说明书是纸上的东 西，在概要设计时期不能专门好地继承、利用需求分析说明书，设计、编制概要设计时必须从零开始，需 要重新分析、明白得需求分析，这种思维上的脱节，不仅延缓开发进度、加重设计人员的负担，而且由于 明白得上的不同导致不同时期描述的对象有许多不相容情形。这些分离使得文档在系统的设计、开发、爱 护中的作用下降，这也是专门多软件人员不情愿编写文档的要紧缘故

9、。二、程序与文档合一的概念提出如何样才是好的文档系统呢？应当具备以下属性：1. 能够准确地描述软件、同时简单易明白；2. 能够迅速错误定位、阻碍分析、修正设计；3. 能够提高软件爱护质量；4. 能够方便程序修改时明白得程序。为此提出了程序与文档合一的概念。这概念使软件成为真正意义上的软件：程序+文档，程序确实是文 档，文档集成在程序中。它要求在选择开发环境时不仅要考虑环境对设计、开发的完美支持，而且要考虑 对爱护、文档的支持；它要求软件人员在设计、开发过程中要考虑爱护问题、文档问题；它要求程序与文 档储备在同一位置、同一系统中；它要求使用相同工具进行程序与文档的书写、检索；它要求在编写和爱 护

10、程序的同时形成文档，在书写文档时编写、爱护程序。程序与文档合一的概念不仅存在于系统的设计、 开发时期而且存在于系统的爱护时期，它贯穿软件的生命周期。动态文档系统是建立在程序与文档合一的概念基础上的、文档与程序一致的、简单易明白的联机文档 系统。它包括构件说明与数据描述、对构件与构件之间、构件与数据之间的关系进行的描述。动态文档系 统是提高了文档的可用性、易用性和连贯性，使文档更加有效，是解决爱护问题的有效途径。 动态文档系统问题分析需要解决的问题是：软件文档的内容划分与猎取、文档的储备与爱护、文档的检索、软件文档的生成 打印。一、软件文档的内容划分成：语义文档、结构文档、过程文档语义文档是对软

11、件的功能、概念、总体设计、流程、规约等用自然语言的描述，是软件人员依照规范 在使用CASE工具编写并填入程序的文档，它也是为更全面的说明文档而灵活加入的额外信息。结构文档是在软件设计工具、开发环境中对象的属性、构件间接口、构件间引用关系、软件的结构等 的描述。利用词法、语法分析程序对整个系统的对象、构件进行识别、分析，猎取上述描述并形成表格文 件。过程文档是对软件的设计、编码、爱护过程中形成的过程描述和程序注释，如设计目的、设计人、时 刻等说明，利用开发环境对软件人员在设计、开发、爱护过程中操作的记录形成操作跟踪。二、程序与文档的统一储备与爱护依照程序与文档合一的概念和文档从程序中提取的要求，

12、文档必须存放在程序中，甚至文档固有的源 代码中。结构如此的程序源代码的储备必须采纳一种新技术一对象仓储(Repository )技术，而不能采纳流 式文件，如此才能使程序与文档既结合又分离。程序与文档结合在一个对象仓储中，结合在统一的开发环 境中；结合在修改代码时能够同时修改文档、修改文档时能够同时人工检查和修改程序，并在多次文档生 成而可不能丢失手工输入的文档。程序与文档应当分别存放在对象仓储中的不同表或不同的字段中，在编 译与运行时分离。三、文档的检索对单个对象、构件文档的检索方式是若于文档存放在一个对象仓储中，它能够随源代码一起检索和爱 护。这种检索给分析和爱护单个构件、对象提供文档支持

13、。建立多种视图、编写程序对整个系统进行文档 的检索和猎取，完成对整个系统的分析，对整个系统进行实时文档支持。这将在例子中较详细的描述。四、软件文档的生成打印编写程序检索和猎取整个系统的文档，按照国家软件标准的文档式样建立文档模板并将按模板生成文 档和利用文字处理软件强大的功能进行创建、编辑文档并打印。依照上述分析，文档分布和猎取对开发环境提出了要求：开发环境应该是设计工具、开发工具的集成， 应该基于CASE技术、对象仓储技术、构件技术、OLE技术。基于CASE技术的开发环境；设计、开发、 爱护过程中形成的文档并植入程序代码中，使文档成为程序的一部分。基于对象仓储技术的开发环境，将 文档与程序统

14、一储备在对象仓储中方便检索。基于构件技术的开发环境，便于识别、猎取构件，分析、形 成结构文档和过程文档。基于OLE等技术使文档能够专门好地利用Word等文档处理软件。 动态文档系统的一个应用实例广州电信科技开发自行设计、开发的名为九七系统的庞大的电信治理运算机系统自 1997 年投产验收 后，将长期用于生产，爱护工作专门重要和紧迫。这为动态文档系统提供了需求和试验场所。在长期爱护 的过程中，体会到好文档的重要性并提出了程序文档合一的概念，这为动态文档系统提供了理论基础。九 七系统是使用 Uniface 开发环境。这种开发环境采纳了 CASE 技术、对象仓储技术、构件技术，这为动态 文档系统提供

15、了技术支撑。一、广州电信动态文档系统的建立步骤1. 明白得Uniface、Oracle工具的开发环境，规划语义文档在各级对象中存放的表与字段，并依照工具的特性制定填写的规则。2. 查找结构文档、过程文档在 Uniface、 Oracle 工具中存放的表与字段。3. 在设计、开发和爱护软件的过程中对这些表或字段按照规则进行填写。4. 建立一整套模板使文档结构与信息源建立映像，包括：数据字典模板、设计文档模板、结构文档模 板、开发过程文档模板等。5. 将这些模板组装成文档系统，并使它独立于开发目标系统。 广州电信动态文档系统的组成能够分为文档查询、爱护记录查询、文档生成。 文档查询不仅包括构件说明

16、与数据描述，而且包括对构件与数据之间的关系的描述，是实时的联机文 档查询系统。爱护记录查询是对软件爱护过程中的各个环节进程进行记录与追踪，用于规范爱护工作。它 包括问题报告、问题分析、错误定位、爱护设计、爱护执行、确认测试、爱护评审、爱护提交、问题跟踪 等。文档生成则是依照需要实时生成软件设计说明书。二、程序与文档合一概念与动态文档系统的意义 广州电信动态文档系统的差不多任务是辅助错误定位、爱护阻碍分析、记录爱护进程、生成文档。使用Uniface的开发环境开发的，能够安装在用Uniface开发的不同的应用系统中。该系统差不多在九七计费 系统的爱护中发挥重要作用。它推崇的程序与文档合一的概念，提出文档确实是程序，程序确实是文档的思路，文档融合在程序中 的构思并已实现，这一概念指导了软件人员进行有效地工作。合一的概念贯