程序文档合一与动态文档

中国IT动力,最新最全的IT技术教程

最新100篇 | 推荐100篇 | 专题100篇 | 排行榜 | 搜索 | 在线API文档 | 网通镜像

当前位置：> 程序开发 > 软件工程 > 综合文章

程序文档合一与动态文档

作者:未知时间:2005-09-13 19:45 出处:ChinaUnix.net 责编:chinaitpower

摘要：程序文档合一与动态文档

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

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

一、目前软件的状况

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

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

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

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

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

　　怎样才是好的文档系统呢？应当具备以下属性：
　　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工具—未使用对象仓储技术、构件技术开发的软件—中实现程序与文档的合一与分离。大型软件系统的环境是复杂的，往往采用了多种开发环境，如何对其他开发环境进行支持还要进行技术探讨和实践上的摸索。

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

threehair 回复于：2003-08-18 12:34:33

这个问题的确值得好好研究一下

一无所有回复于：2003-08-18 17:04:24

文档的管理历来是我们中国程序员的一个“罩门”
希望大家在看到文档对规范的作用的同时，对文档的管理会有一些感性的认识

李大屠娇回复于：2003-08-18 20:59:35

楼主，怎么能够把广州电信的文档要求贴了出来？有人会有意见的。

无双回复于：2003-08-19 13:27:04

这应该是作者公开发表的吧

不用怕了

如果是内部文档的话我想没有人会贴出来的

只爱红酒回复于：2003-08-19 20:15:47

很早在国外的软件工人流水线上就有类似的方式，具体的情况是在详细设计文档中填写代码，后软件规模扩大后，遇到文挡和代码维护的双重问题，已经弃置不用了。
建议使用目前规范的开发管理工具。

li2002 回复于：2003-08-22 07:13:45

这种合一的方法可行吗，怀疑ing～～

无双回复于：2003-08-22 12:15:50

我也不知道

但如果不用动态文档那么代码和文档的维护必然会脱离

当然可以采用XP方法保证尽可能少的文档文档只是起交流作用而不是维护软件更新结果

只爱红酒回复于：2003-08-22 13:22:40

XP更适合项目开发，不十分适合产品。

无双回复于：2003-08-22 17:30:01

产品是不是需要有完备的文档啊以前看到他们做外包是的需要提供完整的文档

不过代码变化那么快开始的文档到了后面也会难维护
我的看法还是开始文档先做交流用

设计到一个阶段后再写文档做维护用

只爱红酒回复于：2003-08-22 19:35:26

实际上需要什么样的文档和采用什么样的开发方法息息相关。
比较健全的文档体系是采用“瀑布法”开发的应用软件，从需求分析到概要设计到详细设计一应惧全，但是软件工程已经证明，“瀑布式开发方法”是系统修改、升级代价最大的一种方法，因此基于这种方法开发的系统往往后期的本地化修改和升级工作让人不堪重负。

新的开发方法早以应运而生，不管是叠待法、原形法以至后来的XP法不断涌现，但大家对其中文档的作用和要求认识不一，运用方法也随经验而定，因此很难总结出适应面广、有推广价值的经验。

对文档的认识很多人都有误区——认为是系统构造和代码的翻版，是软件的解释说明，这无疑是有意义的，但不仅对开发设计者缺少帮助，而且新介入不容易理解，更不用说增加员工的工作量了。

如何正确使用文档，使其成为软件系统建造者的工具？这首先要改变对文档的认识——[b:21b4e27055]文档不是系统构造和代码的翻版，不是软件的解释说明，而是规范软件构成的标准。[/b:21b4e27055]就是说，通过不同的文档规范不同深度的系统设计标准。

宏观的设计规范软件的整体框架，系统间的关系，在整个层次上指导或规范软件系统的行为。常观的文档规范模块级构成和模块间的关系。微观的文档指导模块内部的结构和逻辑，但是不必要描述太细微的比看程序还罗嗦的算法。

这样的文档由不同层次的设计、开发人员组织，只指导、规范下一个工作步骤的内容，从结果上看，最后的文档内容与原来基本相同，但组织结构大有区别，应用方法也有不同，当然，软件开发管理也需跟上。

无双回复于：2003-08-22 22:13:30

但是软件框架总是会变的
开始设计的结构无论是宏观还是微观后面都会有很大变化

需求的变化改变软件结构和算法

所以现在想用文档来指导软件开发还比较难
除非定义的只是模块间接口

对内部实现不作规定这样可以保证软件的松耦合一个部分的变化不会影响其它部分
这几天看了看一些开源软件发现他们就是这样做的
把系统分成几个模块之间定义调用方式与接口这样一个模块的变化不会影响其它模块这样的话只要写出模块间接口文档指导开发就可以了

一无所有回复于：2003-08-23 11:53:41

[quote:90dd3f8af0="只爱红酒"]文档不是系统构造和代码的翻版，不是软件的解释说明，而是规范软件构成的标准[/quote:90dd3f8af0]
这话有道理。文档本来就是规范，是为了让项目干系人有共同语言和共同理解。

只爱红酒回复于：2003-08-25 09:53:30

——“除非定义的只是模块间接口”

模块间接口实际是一个设计规范，而如果设计一个可维护性强的系统（而不是开源软件的分散维护），就需要多层次的设计规范。

关闭本页