代码与文档同行

半年的测试过程，一直存在一件让我很不爽的事情。PDE提供的文档总是过时的，让我每次测试都得通过与PDE面对面沟通才完成，而且在一些问题上花费的时间很多。有时候在想，为什么文档总是跑在代码的后面。很久才发现，目前，代码与文档是分开，还有就是我们PDE（包括我）的习惯，总是喜欢先搞定代码，却总是忘记文档，或者把文档放在后面。这就造成我们定位错误，维护程序造成巨大的开支。那到底有没有方法让代码与文档同步呢？或者我们把习惯变一下，先写好文档，再写代码。我们PDE真的可以改一下习惯，我觉得这样的习惯真的好处多多，最近我也这样试过。只是不知道我的体会在别人那里是不是一样。先写文档的好处：

1、清楚业务流程，可优化流程，加深业务理解

2、代码思路清晰，加深对技术的理解，对做过的技术更牢固

3、更能写出好质量的代码

4、开发效率更高

说完个人习惯，再接着说代码与文档可不可以同步的呢？这才是我要讲的重点。我在网上找了一下，发现目前有人提出了动态文档这个概念。本人觉得动态文档如果真的可以实现，对我们PDE真的是一个好帮手，让我们轻轻松松完成代码的同时，也完成了文档，真的乐唉。

下面给出网络上对动态的文档分析和总结的过程。

程序与文档合一的概念提出
　　怎样才是好的文档系统呢？应当具备以下属性：
　　1. 能够准确地描述软件、并且简单易懂；
　　2. 能够迅速错误定位、影响分析、修正设计；
　　3. 能够提高软件维护质量；
　　4. 能够方便程序修改时理解程序。

　　为此提出了程序与文档合一的概念。这概念使软件成为真正意义上的软件：程序+文档，程序就是文档，文档集成在程序中。它要求在选择开发环境时不仅要考虑环境对设计、开发的完美支持，而且要考虑对维护、文档的支持；它要求软件人员在设计、开发过程中要考虑维护问题、文档问题；它要求程序与文档存储在同一位置、同一系统中；它要求使用相同工具进行程序与文档的书写、检索；它要求在编写和维护程序的同时形成文档，在书写文档时编写、维护程序。程序与文档合一的概念不仅存在于系统的设计、开发阶段而且存在于系统的维护阶段，它贯穿软件的生命周期。
　　动态文档系统是建立在程序与文档合一的概念基础上的、文档与程序一致的、简单易懂的联机文档系统。它包括构件说明与数据描述、对构件与构件之间、构件与数据之间的关系进行的描述。动态文档系统是提高了文档的可用性、易用性和连贯性，使文档更加有效，是解决维护问题的有效途径。动态文档系统问题分析
　　需要解决的问题是：软件文档的内容划分与获取、文档的存储与维护、文档的检索、软件文档的生成打印。

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

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

文档的检索

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

软件文档的生成打印

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

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

 

 

<!--EndFragment-->