程序文档合一与动态文档

一无所有

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

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


一、目前软件的状况


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


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


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


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

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


　　怎样才是好的文档系统呢？应当具备以下属性：
　　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

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

一无所有

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

李大屠娇

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

无双

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

不用怕了

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

li2002

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

无双

我也不知道

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

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

无双

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

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

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