--------------------------------------------------------------------------------

黎宇 （转载自国家计算机标准和文件模板）

第一篇 文件的编制指导

4 软件生存周期与各种文件的编制

　　一项计算机软件，从出现一个构思之日起，经过这项软件开发成功投入使用，直到最后决定停止使 用，并被另一一项软件代替之时止，被认为是该软件的一个生存周期。一般地说这个软件生存周期可以分成以下六个阶段：

　　可行性与计划研究阶段

　　需求分析阶段

　　设计阶段

　　实现阶段

　　测试阶段

　　运行与维护阶段

　　在可行性研究与计划阶段内，要确定该软件的开发目标和总的要求，要进行可行性分析、投资一收益分析、制订开发计划，并完成应编制的文件。

　　在需求分析阶段内，由系统分析人员对被设计的系统进行系统分析，确定对该软件的各项功能、性能需求和设计约束，确定对文件编制的要求，作为本阶段工作的结果，一般地说，软件需求说明书、数据要求说明书和初步的用户手册应该编写出来。

　　在设计阶段内，系统设计人员和程序设计人员应该在反复理解软件需求的基础上，提出多个设计，分析每个设计能履行的功能并进行相互比较，最后确定一个设计，包括该软件的结构、模块的划分、功能的分配以及处理流程。在被设计系统比较复杂的情况下，设计阶段应分解成概要设计阶段和详细设计阶段两个步骤。在一般情况下，应完成的文件包括：概要设计说明书、详细设计说明书和测试计划初稿。

　　在实现阶段内，要完成源程序的编码、编译（或汇编）和排错调试得到无语法错的程序清单，要开始编写模块开发卷宗，并且要完成用户手册、操作手册等面向用户的文件的编写工作，还要完成测试计划的编制。

　　在测试阶段，该程序将被全面地测试，已编制的文件将被检查审阅。一般要完成模块开发卷宗和测试分析报告，作为开发工作的结束，所生产的程序、文件以及开发工作本身将逐项被评价，最后写出项目开发总结报告。

　　在整个开发过程中（即前五个阶段中），开发集体要按月编写开发进度月报。

　　在运行和维护阶段，软件将在运行使用中不断地被维护，根据新提出的需求进行必要而且可能的扩充和删改。

　　对于一项软件而言，其生存周期各阶段与各种文件编写工作的关系可见表互，其中有些文件的编写工作可能要在若干个阶段中延续进行。

表1软件生存周期各阶段中的文件编制 

5 文件编制中的考虑因素

　　文件编制是一个不断努力的工作过程。是一个从形成最初轮廓，经反复检查和修改，直到程序和文件正式交付使用的完整过程。其中每一步都要求工作人员做出很大努力。要保证文件编制的质量，要体现每个开发项目的特点，也要注意不要花太多的人力。为此，编制中要考虑如下各项因素。

5．1 文件的读者

　　每一种文件都具有特定的读者。这些读者包括个人或小组、软件开发单位的成员或社会上的公众、从事软件工作的技术人员、管理人员或领导干部。他们期待着使用这些文件的内容来进行工作，例如设计、编写程序、测试、使用、维护或进行计划管理。因此，这些文件的作者必须了解自己的读者，这些文件的编写必须注意适应自己的特定读者的水平、特点和要求。

5．2 重复性

　　本指南第二篇中将列出的这十四种文件的内容要求中，显然存在某些重复。较明显的重复有两类。引言是每一种文件都要包含的内容，以向读者提供总的梗概。第二类明显的重复是各种文件中的说明部分，如对功能性能的说明、对输入和输出的描述、系统中包含的设备等。这是为了方便每种文件各自的读者，每种产品文件应该自成体系，尽量避免读一种文件时又不得不去参考另一种文件。当然，在每一种文件里，有关引言、说明等同其他文件相重复的部分，在行文上、在所用的术语上、在详细的程度上，还是应该有一些差别，以适应各种文件的不同读者的需要。

5．3 灵活性

　　鉴于软件开发是具有创造性的脑力劳动，也鉴于不同软件在规模上和复杂程度上差别极大，本指南认为在文件编制工作中应允许一定的灵活性。这种灵活性表现在如下各款。

5．3．1 应编制的文件种类

　　尽管本指南认为在一般情况下，一项软件的开发过程中，应产生的文件有十四种，然而针对一项具体的软件开发项目，有时不必编制这么多的文件，可以把几种文件合并成一种。一般地说，当项目的规模、复杂性和成败风险增大时，文件编制的范围、管理手续和详细程度将随之增加。反之，则可适当减少。为了恰当地掌握这种灵活性，本指南要求贯彻分工负责的原则，这意味着：

　　a: 一个软件开发单位的领导机构应该根据本单位经营承包的应用软件的专业领域和本单位的管理能力，制定一个对文件编制要求的实施规定，主要是：在不同的条件下，应该形成哪些文件？这些文件的详细程度？该开发单位的每一个项目负责人，必须认真执行这个实施规定。这种规定的两个例子可叹 本指南的附录o（参考件）；

　　b．对于一个具体的应用软件项目，项目负责人应根据上述实施规定，确定一个文件编制计划，主 中包括:

　　（1）应该编制哪几种文件，详细程度如何？

　　（2）各个文件的编制负责人和进度要求；

　　（3）审查、批准的负责人和时间进度安排；

　　（4）在开发时期内，各文件的维护、修改和管理的负责人，以及批准手续。

　　每项工作必须落实到人。

　　这个文件编制计划是整个开发计划的重要组成部分；

　　C．有关的设计人员则必须严格执行这个文件编制计划。

5．3．2 文件的详细程度

　　从同一份提纲起草的文件的篇幅大小往往不同，可以少到几页，也可以长达几百页。对于这种差别本指南是允许的。此详细程度取决于任务的规模、复杂性和项目负责人对该软件的开发过程及运行环与所需要的详细程度的判断。

5．3．3 文件的扩展

　　当被开发系统的规模非常大（例如源码超过一百万行）时，一种文件可以分成几卷编写，可以按其。 每一个系统分别编制，也可以按内容划分成多卷，例如：

　　项目开发计划可能包括：质量保证计划，配置管理计划， 用户培训计划， 安装实施计划；

　　系统设计说明书可分写成：系统设计说明书，子系统设计说明书；

　　程序设计说明书可分写成：程序设计说明书，接口设计说明书，版本说明；

　　操作手册可分写成：操作手册，安装实施过程；

　　测试计划可分写成：测试计划，测试设计说明， 测试规程，测试用例；

　　测试分析报告可分写成：综合测试报告，验收测试报告；

　　项目开发总结报告亦可分写成项目开发总结报告和资源环境统计。

5．3．4 节的扩张与缩并

　　在有些文件中，可以使用本指南所提供的章、条标题，但在条内又存在一系列需要分别讨论的因素 本指南认为，所有的条都可以扩展，可以进一步细分，以适应实际需要。反之，如果章条中的有些细节； 非必需，也可以根据实际情况缩并。此时章条的编号应相应地改变。

5．3．5 程序设计的表现形式

　　本指南对于程序的设计表现形式并未作出规定或限制，可以使用流程图的形式、判定表的形式，1 可以使用其他表现形式，如程序设计语言（PDL）、问题分析图（PAD）等。

5．3．6 文件的表现形式

　　本指南对于文件的表现形式亦未作出规定或限制，可以使用自然语言，也可以使用形式化语言。 5．3．7 文件的其他种类

　　当本指南中规定的文件种类尚不能满足某些应用部门的特殊需要时，他们可以建立一些特殊的文件种类要求，例如软件质量保证计划、软件配置管理计划等，这些要求可以包含在本单位的文件编制实施规定中。

6 文件编制的管理工作

　　文件编制工作必须有管理工作的配合，才能使所编制的文件真正发挥它的作用。文件的编制工作实际上贯穿于一项软件的整个开发过程，因此，对文件的管理必须贯穿于整个开发过程。在开发过程中必须进行的管理工作是以下四条。

6．1文件的形成

　　开发集体中的每个成员，尤其是项目负责人，应该认识到：文件是软件产品的必不可少的组成部分；在软件开发过程的各个阶段中，必须按照规定及时地完成各种产品文件的编写工作；必须把在一个开发步骤中作出的决定和取得的结果及时地写入文件；开发集体必须及时地对这些文件进行严格的评审；这些文件的形成是各个阶段开发工作正式完成的标志。这些文件上必须有编写者、评审者和批准者的签字，必须有编写、评审完成的日期和批准的日期。

6．2文件的分类与标识

　　在软件开发的过程中，产生的文件是很多的，为了便于保存、查找、使用和修改，应该对文件按层次地加以分类组织。一个软件开发单位应该建立一个对本单位文件的标识方法，使文件的每一页都具有明确的标识。例如可以按如下四个层次对文件加以分类和标识。

　　a．文件所属的项目的标识；

　　b．文件种类的标识；

　　C．同一种文件的不同版本号；

　　d．页号。

　　此外，对每种文件还应根据项目的性质，划定它们各自的保密级别，确定他们各自的发行范围。

6．3文件的控制

　　在一项软件的开发过程中，随着程序的逐步形成和逐步修改，各种文件亦在不断地产生、不断地修改或补充。因此，必须加以周密的控制，以保持文件与程序产品的一致性，保持各种文件之间的一致性和文件的安全性。这种控制表现为：

　　a．就从事一项软件开发工作的开发集体而言，应设置一位专职的文件管理人员（接口管理工程师或文件管理员）；在开发集体中，应该集中保管本项目现有全部文件的主文本两套，由该文件管理人员负责保管；

　　b．每一份提交给文件管理人员的文件都必须具有编写人、审核人和批准人的签字；

　　C．这两套主文本的内容必须完全一致；其中有一套是可供出借的，另一套是绝对不能出借的，以免发生万一；可出借的主文本在出借时必须办理出借手续，归还时办理注销出借手续；

　　d．开发集体中的工作人员可以根据工作的需要，在本项目的开发过程中持有一些文件，即所谓个人文件，包括为使他完成他承担的任务所需要的文件，以及他在完成任务过程中所编制的文件；但这种个人文件必须是主文本的复制品，必须同主文本完全一致，若要修改，必须首先修改主文本；

　　e．不同开发人员所拥有的个人文件通常是主文本的各种子集；所谓子集是指把主文本的各个部分根据承担不同任务的人员或部门的工作需要加以复制、组装而成的若干个文件的集合；文件管理人员。应该列出一份不同子集的分发对象的清单，按照清单及时把文件分发给有关人员或部门；

　　f．一份文件如果已经被另一份新的文件所代替，则原文件应该被注销；文件管理人中要随时整理主文本，及时反映出文件的变化和增加情况，及时分发文件；

　　g．当一个项目的开发工作临近结束时，文件管理人员应逐个收回开发集体内每个成员的个人文 件，并检查这些个人文件的内容；经验表明，这些个人文件往往可能比主文本更详细，或同主文本的内容 有所不同，必须认真监督有关人员进行修改，使主文本能真正反映实际的开发结果。

6．4文件的修改管理

　　在一个项目的开发过程中的任何时刻，开发集体内的所有成员都可能对开发工作的已有成果-- 文件，提出进行修改的要求。提出修改要求的理由可能是各种各样的，进行修改而引起的影响可能很小， 也可能会牵涉到本项目的很多方面。因此，修改活动的进行必须谨慎，必须对修改活动的进行加以管理， 必须执行修改活动的规程，使整个修改活动有控制地进行。

　　修改活动可分如下五个步骤进行：

　　a．提议开发集体中的任何一个成员都可以向项目负责人提出修改建议，为此应该填写一份修 改建议表，说明修改的内容、所修改的文件和部位、以及修改理由；

　　b．评议由项目负责人或项目负责人指定的人员对该修改建议进行评议，包括审查该项修改的 必要性、确定这一修改的影响范围、研究进行修改的方法、步骤和实施计划；

　　c．审核一般由项目负责人进行审核，包括核实修改的自的和要求、核实修改活动将带来的影 响、审核修改活动计划是否可行；

　　d．批准在一般情况下，批准权属于该开发单位的部门负责人；在批准时，主要是决断修改工作 中各项活动的先后顺序及各自的完成日期，以保证整个开发工作按原定计划日期完成；

　　e．实施由项目负责人按照已批准的修改活动计划，安排各项修改活动的负责人员进行修改，建 立修改记录、产生新的文件以取代原有文件、最后把文件交文件管理人员归档，并分发给有关的持有者。

如果想了解更多相关内容请访问:

http://51cmm.csai.cn/SoftDocuments/No020.htm

--------------------------------------------------------------------------------

黎宇 （转载自国家计算机标准和文件模板）

1 引言

1．1编写目的

　　说明编写这份详细设计说明书的目的，指出预期的读者。

1．2背景

　　说明：

　　a．待开发软件系统的名称；

　　b．本项目的任务提出者、开发者、用户和运行该程序系统的计算中心。

1．3定义

　　列出本文件中用到专门术语的定义和外文首字母组词的原词组。

1．4参考资料

　　列出有关的参考资料，如：

　　a．本项目的经核准的计划任务书或合同、上级机关的批文；

　　b．属于本项目的其他已发表的文件；

　　c．本文件中各处引用到的文件资料，包括所要用到的软件开发标准。 列出这些文件的标题、文件编号、发表日期和出版单位，说明能够取得这些文件的来源。

2　程序系统的结构

　　用一系列图表列出本程序系统内的每个程序（包括每个模块和子程序）的名称、标识符和它们之间 的层次结构关系。

3　程序1（标识符）设计说明

　　从本章开始，逐个地给出各个层次中的每个程序的设计考虑。以下给出的提纲是针对一般情况的。 对于一个具体的模块，尤其是层次比较低的模块或子程序，其很多条目的内容往往与它所隶属的上一层 模块的对应条目的内容相同，在这种情况下，只要简单地说明这一点即可。

3．1程序描述

　　给出对该程序的简要描述，主要说明安排设计本程序的目的意义，并且，还要说明本程序的特点（如 是常驻内存还是非常驻？是否子程序？是可重人的还是不可重人的？有无覆盖要求？是顺序处理还是并发 处理卜…．．等）。

3．2功能

　　说明该程序应具有的功能，可采用IPO图（即输入一处理一输出图）的形式。

3．3性能

　　说明对该程序的全部性能要求，包括对精度、灵活性和时间特性的要求。

3．4输人项

　　给出对每一个输入项的特性，包括名称、标识、数据的类型和格式、数据值的有效范围、输入的方式。 数量和频度、输入媒体、输入数据的来源和安全保密条件等等。

3． 5输出项

　　给出对每一个输出项的特性，包括名称、标识、数据的类型和格式，数据值的有效范围，输出的形式、 数量和频度，输出媒体、对输出图形及符号的说明、安全保密条件等等。

3．6算法

　　详细说明本程序所选用的算法，具体的计算公式和计算步骤。

3．7流程逻辑

　　用图表（例如流程图、判定表等）辅以必要的说明来表示本程序的逻辑流程。

3．8接口

　　用图的形式说明本程序所隶属的上一层模块及隶属于本程序的下一层模块、子程序，说明参数赋值和调用方式，说明与本程序相直接关联的数据结构（数据库、数据文卷）。

3．9存储分配

　　根据需要，说明本程序的存储分配。

3．10注释设计

　　说明准备在本程序中安排的注释，如：

　　a． 加在模块首部的注释；

　　b．加在各分枝点处的注释； 对各变量的功能、范围、缺省条件等所加的注释；

　　d．对使用的逻辑所加的注释等等。

3．11限制条件

　　说明本程序运行中所受到的限制条件。

3．12测试计划

　　说明对本程序进行单体测试的计划，包括对测试的技术要求、输入数据、预期结果、进度安排、人员职责、设备条件驱动程序及桩模块等的规定。

3．13尚未解决的问题

　　说明在本程序的设计中尚未解决而设计者认为在软件完成之前应解决的问题。

4　程序2（标识符）设计说明

　　用类似3的方式，说明第2个程序乃至第N个程序的设计考虑。

如果想了解更多相关内容请访问:

http://51cmm.csai.cn/SoftDocuments/No016.htm

如果想了解更多相关内容请访问:

http://51cmm.csai.cn/SoftDocuments/No021.htm

软件文档知多少？

--------------------------------------------------------------------------------

Fishman

　　如今，软件开发越来越复杂，软件功能也越来越丰富。而几乎所有成熟的商业软件，都是靠一个开发团队齐心协力的血汗结晶。“罗马不是一天建成的！”，当我们震撼于Microsoft Windows的惊世巨著的同时，也道听途说了微软公司软件工程是如何的完善规范。的确，集数百名员工几年的共同努力之大成，软件项目管理的成败是控制开发成本的关键环节。这里面，少不了贯穿其中的重要步骤----软件文档。

　　软件文档可以分为开发文档和产品文档两大类。

　　开发文档包括：《功能要求》、《投标方案》、《需求分析》、《技术分析》、《系统分析》、《数据库文档》、《功能函数文档》、《界面文档》、《编译手册》、《QA文档》、《项目总结》等。

　　产品文档包括：《产品简介》、《产品演示》、《疑问解答》、《功能介绍》、 《技术白皮书》、《评测报告》、《安装手册》、《使用手册》、《维护手册》、 《用户报告》、《销售培训》等。

一、开发文档

　　1. 《功能要求》--来源于客户要求和市场调查，是软件开发中最早期的一个环节。客户提出一个模糊的功能概念，或者要求解决一个实际问题，或者参照同类软件的一个功能。有软件经验的客户还会提供比较详细的技术规范书，把他们的要求全部列表书写在文档中，必要时加以图表解说。这份文档是需求分析的基础。

　　2. 《投标方案》--根据用户的功能要求，经过与招标方沟通和确认，技术人员开始书写《投标方案》，方案书一般包括以下几个重要的章节：

　　前言--项目背景、公司背景和业务、技术人员结构、公司的成功案例介绍等。

　　需求分析--项目要求、软件结构、功能列表、功能描述、注意事项等。

　　技术方案--总体要求和指导思想、技术解决方案、软件开发平台、网络结构体系等。

　　项目管理--描述公司的软件开发流程、工程实施服务、组织和人员分工、开发进度控制、软件质量保证、项目验收和人员培训、软件资料文档等。

　　技术支持--公司的技术支持和服务介绍、服务宗旨和目标、服务级别和响应时间、技术服务区域、技术服务期限、授权用户联系人等。

　　系统报价--软、硬件平台报价列表、软件开发费用、系统维护费用等。

　　项目进度--整个项目的进度计划，包括签署合同、项目启动、需求分析、系统分析、程序开发、测试维护、系统集成、用户验收、用户培训等步骤的时间规划。

　　3. 《需求分析》--包括产品概述、主要概念、操作流程、功能列表和解说、注意事项、系统环境等。以《功能要求》为基础，进行详细的功能分析(包括客户提出的要求和根据开发经验建议的功能)，列出本产品是什么，有什么特殊的概念，包括那些功能分类，需要具备什么功能，该功能的操作如何，实现的时候该注意什么细节，客户有什么要求，系统运行环境的要求等。这里的功能描述跟以后的使用手册是一致的。

　　4. 《技术分析》--包括技术选型、技术比较、开发人员、关键技术问题的解决、技术风险、技术升级方向、技术方案评价，竞争对手技术分析等。以《需求分析》为基础，进行详细的技术分析(产品的性能和实现方法)，列出本项目需要使用什么技术方案，为什么，有哪些技术问题要解决 ，估计开发期间会碰到什么困难，技术方案以后如何升级，对本项目的技术有什么评价等。

　　5. 《系统分析》--包括功能实现、模块组成、功能流程图、函数接口、数据字典、软件开发需要考虑的各种问题等。以《需求分析》为基础，进行详细的系统分析(产品的开发和实现方法)，估计开发期间需要把什么问题说明白，程序员根据《系统分析》，开始在项目主管的带领下进行编码。

　　6. 《数据库文档》--包括数据库名称、表名、字段名、字段类型、字段说明、备注、字段数值计算公式等。以《系统分析》为基础，进行详细的数据库设计。必要时可以用图表解说，特别是关系数据库。

　　7. 《功能函数文档》--包括变量名、变量初植、功能，函数名，参数，如何调用、备注、注意事项等。以《系统分析》为基础，进行详细的说明，列出哪个功能涉及多少个函数，以便以后程序员修改、接手和扩展。

　　8. 《界面文档》--包括软件外观、界面素材、编辑工具、文件名、菜单、按钮和其它界面部件的要求，这里与软件完成后的运行界面是一致的。

　　9. 《编译手册》--包括服务器编译环境、操作系统、编译工具、GNU的C++编译器版本信息、目录说明、程序生成、源程序文件列表、Makefile配置及其相关程序的对应关系列表。客户端的编译过程、编译结果、编译示例、编译环境、操作系统、编译工具、源文件列表和制作安装程序的过程。

　　10. 《QA文档》--包括产品简介、产品原理、产品功能列表、功能描述、功能流程、执行结果、数据库结构、测试要求等，提供给软件测试人员使用。

　　11. 《项目总结》--包括项目简介、项目参与人员和开发时间、项目风险管理过程、项目功能列表、项目结构特点、技术特点、对项目的升级建议、对以后的项目的建议、人员素质情况等。

二、产品文档

　　1. 《产品简介》--包括公司背景、产品概念、适用范围、产品功能、功能特点、运行要求和公司联系地址。

　　2. 《产品演示》--包括公司简介、产品背景、产品描述、产品特点、产品作用、适用范围、使用分析、功能模块、解决问题、合作伙伴、成功案例等。一般用Power

point或者VCD录制软件实现。

　　3. 《疑问解答》--列出用户关心的问题和处理方法。用于解答软件的操作功能和解决用户的疑难问题。

　　4. 《功能介绍》--以《需求分析》为书写基础，包括软件介绍、软件结构、功能列表、功能描述和公司联系地址。

　　5. 《技术白皮书》--以《技术分析》为书写基础，包括功能实现、技术选型、关键技术问题的解决、技术方案特点、技术升级方向等。

　　6. 《评测报告》--第三方权威评测报告。包括评测目的、评测范围、评测环境、评测内容、实测数据、性能表现、结果分析和评测总结等。

　　7. 《安装手册》--包括系统环境、运行平台、产品安装过程、初始环境设置、安装记录等。

　　8. 《使用手册》--包括产品简介、功能列表、功能描述和解释、功能操作、客户服务和联系方式等。

　　9. 《维护手册》--包括产品简介、系统须知、初始环境设置、系统配置、数据管理和备份、技术问题解答和联系方式等。

　　10. 《用户报告》--包括产品简介、购买时间、使用目的、使用时间、使用地点、实施过程、出现问题和解决、产品总结和建议等。

　　11.《销售培训》--包括项目简介、产品功能、产品特点、商业优势、系统运行环境、适用范围、目标客户等。

如果想了解更多相关内容请访问:

http://51cmm.csai.cn/SoftDocuments/No008.htm

--------------------------------------------------------------------------------

　　在整个软件生存期中，各种文档作为半成品或是最终成品， 会不断地生成、修改或补充。为了最终得到高质量的产品，达到上 节提出的质量要求，必须加强对文档的管理。以下几个方面是应注意做到的：

　　①软件开发小组应设一位文档保管人员，负责集中保管本 项目已有文档的两套主文本。两套文本内容完全一致。其中的一套可按一定手续，办理借阅。

　　②软件开发小组的成员可根据工作需要在自己手中保存一些个人文档。这些一般都应是主文本的复制件，并注意和主文本保持一致，在作必要的修改时，也应先修改主文本。

　　③开发人员个人只保存着主文本中与他工作相关的部分文档。

　　④在新文档取代了旧文档时，管理人员应及时注销旧文档。 在文档内容有更动时，管理人员应随时修订主文本，使其及时反映更新了的内容。

　　⑤项目开发结束时，文档管理人员应收回开发人员的个人文档。发现个人文档与主文本有差别时，应立即着手解决。这常常是未及时修订主文本造成的。

　　⑥在软件开发过程中，可能发现需要修改已完成的文档，特别是规模较大的项目，主文本的修改必须特别谨慎。修改以前要充分估计修改可能带来的影响，并且要按照：提议、评议、审核、批准和实施等步骤加以严格的控制。

如果想了解更多相关内容请访问:

http://51cmm.csai.cn/SoftDocuments/No006.htm

如果想了解更多相关内容请访问:

http://51cmm.csai.cn/SoftDocuments/No020.htm

--------------------------------------------------------------------------------

洪海 廖静

　　很多企业已经建立了许多庞大的计算机管理系统，而且将不断地推出新的系统。满足经营的需求须不断维护、改造计算机系统，但同时又要不影响现行生产，所以必须建立一整套机制来评价、控制和完成对系统的维护。在软件维护过程中，提出程序与文档合一的概念在软件开发的同时建立动态文档。

程序与文档合一概念的提出

一、目前软件的状况

　　程序与文档的形式分离，不仅是用各自独立的形式存放，而且使用不同的工具在不同的时间里书写和检索。维护程序时不能方便地得到文档的帮助，不能同步修改文档。

　　程序与文档的内容分离，由于程序与文档采用不同的描述，既有计算机语言也有自然语言。维护过程中不能及时、一致地更新文档或程序，使文档不能准确地描述程序而几乎成为废纸甚至带来负面价值。

　　软件开发与维护的分离，绝大多数软件在设计、开发时不太考虑以后可能的修改，加大了软件维护的难度，而且使维护容易引入新的错误。

　　这些分离也表现在设计、开发的不同阶段的文档之间的不相容性，例如：需求分析说明书是纸上的东西，在概要设计阶段不能很好地继承、利用需求分析说明书，设计、编制概要设计时必须从零开始，需要重新分析、理解需求分析，这种思维上的脱节，不仅延缓开发进度、加重设计人员的负担，而且由于理解上的不同导致不同阶段描述的对象有许多不相容情况。这些分离使得文档在系统的设计、开发、维护中的作用下降，这也是很多软件人员不愿意编写文档的主要原因。

二、程序与文档合一的概念提出

　　怎样才是好的文档系统呢？应当具备以下属性：

　　1. 能够准确地描述软件、并且简单易懂；

　　2. 能够迅速错误定位、影响分析、修正设计；

　　3. 能够提高软件维护质量；

　　4. 能够方便程序修改时理解程序。

　　为此提出了程序与文档合一的概念。这概念使软件成为真正意义上的软件：程序+文档，程序就是文档，文档集成在程序中。它要求在选择开发环境时不仅要考虑环境对设计、开发的完美支持，而且要考虑对维护、文档的支持；它要求软件人员在设计、开发过程中要考虑维护问题、文档问题；它要求程序与文档存储在同一位置、同一系统中；它要求使用相同工具进行程序与文档的书写、检索；它要求在编写和维护程序的同时形成文档，在书写文档时编写、维护程序。程序与文档合一的概念不仅存在于系统的设计、开发阶段而且存在于系统的维护阶段，它贯穿软件的生命周期。

　　动态文档系统是建立在程序与文档合一的概念基础上的、文档与程序一致的、简单易懂的联机文档系统。它包括构件说明与数据描述、对构件与构件之间、构件与数据之间的关系进行的描述。动态文档系统是提高了文档的可用性、易用性和连贯性，使文档更加有效，是解决维护问题的有效途径。

动态文档系统问题分析

　　需要解决的问题是：软件文档的内容划分与获取、文档的存储与维护、文档的检索、软件文档的生成打印。

一、软件文档的内容划分成：语义文档、结构文档、过程文档

　　语义文档是对软件的功能、概念、总体设计、流程、规约等用自然语言的描述，是软件人员根据规范在使用CASE工具编写并填入程序的文档，它也是为更全面的解释文档而灵活加入的额外信息。

　　结构文档是在软件设计工具、开发环境中对象的属性、构件间接口、构件间引用关系、软件的结构等的描述。利用词法、语法分析程序对整个系统的对象、构件进行识别、分析，获取上述描述并形成表格文件。

　　过程文档是对软件的设计、编码、维护过程中形成的过程描述和程序注释，如设计目的、设计人、时间等说明，利用开发环境对软件人员在设计、开发、维护过程中操作的记录形成操作跟踪。

二、程序与文档的统一存储与维护

　　根据程序与文档合一的概念和文档从程序中提取的要求，文档必须存放在程序中，甚至文档固有的源代码中。结构如此的程序源代码的存储必须采用一种新技术—对象仓储（Repository）技术，而不能采用流式文件，这样才能使程序与文档既结合又分离。程序与文档结合在一个对象仓储中，结合在统一的开发环境中；结合在修改代码时可以同时修改文档、修改文档时可以同时人工检查和修改程序，并在多次文档生成而不会丢失手工输入的文档。程序与文档应当分别存放在对象仓储中的不同表或不同的字段中，在编译与运行时分离。

三、文档的检索

　　对单个对象、构件文档的检索方式是若于文档存放在一个对象仓储中，它可以随源代码一起检索和维护。这种检索给分析和维护单个构件、对象提供文档支持。建立多种视图、编写程序对整个系统进行文档的检索和获取，完成对整个系统的分析，对整个系统进行实时文档支持。这将在例子中较详细的描述。

四、软件文档的生成打印

　　编写程序检索和获取整个系统的文档，按照国家软件标准的文档式样建立文档模板并将按模板生成文档和利用文字处理软件强大的功能进行创建、编辑文档并打印。

　　根据上述分析，文档分布和获取对开发环境提出了要求：开发环境应该是设计工具、开发工具的集成，应该基于CASE技术、对象仓储技术、构件技术、OLE技术。基于CASE技术的开发环境；设计、开发、维护过程中形成的文档并植入程序代码中，使文档成为程序的一部分。基于对象仓储技术的开发环境，将文档与程序统一存储在对象仓储中方便检索。基于构件技术的开发环境，便于识别、获取构件，分析、形成结构文档和过程文档。基于OLE等技术使文档可以很好地利用Word等文档处理软件。

动态文档系统的一个应用实例

　　广州电信科技开发有限公司自行设计、开发的名为九七系统的庞大的电信管理计算机系统自1997年投产验收后，将长期用于生产，维护工作非常重要和紧迫。这为动态文档系统提供了需求和试验场所。在长期维护的过程中，体会到好文档的重要性并提出了程序文档合一的概念，这为动态文档系统提供了理论基础。九七系统是使用Uniface开发环境。这种开发环境采用了CASE技术、对象仓储技术、构件技术，这为动态文档系统提供了技术支撑。

一、广州电信动态文档系统的建立步骤

　　1. 理解Uniface、Oracle工具的开发环境，规划语义文档在各级对象中存放的表与字段，并根据工具的特性制定填写的规则。

　　2. 寻找结构文档、过程文档在Uniface、Oracle工具中存放的表与字段。

　　3. 在设计、开发和维护软件的过程中对这些表或字段按照规则进行填写。

　　4. 建立一整套模板使文档结构与信息源建立映像，包括：数据字典模板、设计文档模板、结构文档模板、开发过程文档模板等。

　　5. 将这些模板组装成文档系统，并使它独立于开发目标系统。

　　广州电信动态文档系统的组成可以分为文档查询、维护记录查询、文档生成。

　　文档查询不仅包括构件说明与数据描述，而且包括对构件与数据之间的关系的描述，是实时的联机文档查询系统。维护记录查询是对软件维护过程中的各个环节进程进行记录与追踪，用于规范维护工作。它包括问题报告、问题分析、错误定位、维护设计、维护执行、确认测试、维护评审、维护提交、问题跟踪等。文档生成则是根据需要实时生成软件设计说明书。

二、程序与文档合一概念与动态文档系统的意义

　　广州电信动态文档系统的基本任务是辅助错误定位、维护影响分析、记录维护进程、生成文档。使用Uniface的开发环境开发的，可以安装在用Uniface开发的不同的应用系统中。该系统已经在九七计费系统的维护中发挥重要作用。

　　它推崇的程序与文档合一的概念，提出文档就是程序，程序就是文档的思路，文档融合在程序中的构思并已实现，这一概念指导了软件人员进行有效地工作。合一的概念贯穿了设计、开发、维护整个软件周期，保证了文档之间的继承性和一致性，在设计、开发每一阶段是继承前阶段的程序和文档的结果。这样极大地消除了程序与文档、文档与文档之间的不一致性，加快了软件设计进度，提高了软件开发、维护的质量。它是软件工程在具体应用中的一种尝试，它从程序文档合一的角度出发，进一步规范软件设计、开发、维护。程序文档合一的概念为软件开发环境发展提供了一种思路；设计更好的对象仓储来满足开发、维护人员对程序文档合一的概念的需求。

动态文档系统的局限与发展

　　广州电信动态文档系统有很大的局限性，只能用于Uniface或Oracle开发的系统中。目前的广州电信动态文档系统的构件的识别与获取主要依赖开发工具提供的构件和构件的特征进行识别的。这种动态文档系统难以在一些3GL工具—未使用对象仓储技术、构件技术开发的软件—中实现程序与文档的合一与分离。大型软件系统的环境是复杂的，往往采用了多种开发环境，如何对其他开发环境进行支持还要进行技术探讨和实践上的摸索。

　　另一个局限问题是目前的动态文档系统描述的是程序文档，其主要在编码、维护的过程中进行建设，系统进入维护阶段使用。如何使动态文档系统不仅对软件维护阶段进行支持，而且对软件的设计、开发阶段进行更多的支持？一种可能的解决途径是将软件复用技术拓宽到包括文档复用，包括程序复用、程序文档复用和设计文档复用，而且将动态文档系统建立在基于这种软件复用系统之上。

如果想了解更多相关内容请访问:

http://51cmm.csai.cn/SoftDocuments/No005.htm