文档自动化视频在线视频

嗨，大家好

今天我们来讨论文档自动化的话题

说到文档，没有人会否认文档的重要性

但是对于程序员来说，写文档真的是一件不爱干

却不得不干的事情

前面我们在讨论方法论的时候也说过

重型开发方法的一个重要特征就是中间产物很多

这个中间产物，主要就是指文档

所以敏捷方法强调，文档只写必要的文档

多余的文档对客户对开发人员都是一种负担

一个逼着看文档，一个逼着写文档，都不好受

从程序员角度来说，不爱写文档主要是觉得

写了白写，没人爱看

进一步分析，为什么没人爱看

是因为文档总过时，看了文档也和代码对不上

于是就不爱看了

那么如何解决这个问题呢？

团队管理者应该积极引入文档自动化技术

简化文档生成过程

减轻开发人员的文档编写负担

更重要的是，通过文档自动化技术

可以维持文档与设计模型和代码之间的一致性

保证文档的精确性和时效性

开发人员只需要维护单一源头

也就是设计模型或者代码

需要更新文档的时候，可以一键生成最新的文档

在早期软件开发活动中，设计和编码是分开的

由不同的人员使用不同的设计开发工具，各做各
的

程序员在编码的时候很容易就偏离设计

现在呢，大的IDE厂商在IDE中集成了多工种平台

架构师、设计师和程序员可以在同一个IDE中进
行设计和开发

从类图到代码，从UML模型到html文档，再加上
版本控制工具

不同工种人员之间的协作更加顺畅了

大家这里看到的是vs.net IDE中的together建模工
具

这是类图的鹰眼导航

这是设计文档的自动生成

Together的类图和代码之间实时双向同步功能

让文档的编写和生成不再是痛苦的事情

说到双向实时同步功能

不得不说这是一个十分让人兴奋的特性

之前的建模工具一般是单向手工生成的

画好类图之后，点击菜单，选择生成语言

问你选Java还是C++，然后生成对应的类的框架
代码

类图改动后，需要重新操作这个过程

或者你修改了代码，而类图还是原来的设计

这种代码单向生成功能往往比较鸡肋

食之无味，弃之可惜

当初为什么Borland公司会重金收购Together这家
小公司

就是看中了together的LiveSource实时双向同步技
术

这项技术有力的推动了软件自动化技术的发展

在实际开发中，无论你之前拥有多么漂亮的UML
模型图

在编码阶段都会出现偏差，无法保证模型和代码
同步

尤其是不同的开发人员使用不同开发工具的情况
下

这种情况更为严重

从某种意义上来说，UML模型，尤其是类图

它本身也是一种非常重要的文档

但是，在编码过程中，最开始的那个UML类图

已经过时了，没用了

如何从最新的代码中得到最新的类图呢？

这里的示例演示了如何简单的完成这一点

这个例子中结合使用了UMLGraph 和 Javadoc

生成了html格式UML类图

具体做法就是，在构建脚本中把代码中

我们想提取的那些Javadoc注释属性传递给
UmlGraphDoc

然后就会生成和代码一致的UML类图

这些操作被封装在脚本里

可以在持续集成中自动的跑起来

这样，你的每次构建，都会得到最新的文档

这些文档可以被自动发布到开发团队的内部网站
上

每个人随时都可以看到最新的文档

绝大多数的软件系统都会用数据库来存储数据

数据库设计和管理需要很多专业的知识和技能

一般的，我们采用数据库设计工具完成这些工 作

比如我们设计完ER图之后

通过ERWin之类的专业的数据库设计工具

画出逻辑视图和物理视图

确定实体和实体之间的关系

确定主键外键和字段属性等等

这些工具往往可以直接连接数据库

直接把这些物理视图转换成DDL代码，并在数据
库中执行

同时，可以导出为各种格式的数据词典文件作为
数据库设计的文档

这些操作很方便，也很强大

但是，这里依然存在同样的问题

就是文档生成的方向性问题

程序员在编程过程当中如果需要修改

数据库的某个表，表中的某个字段，怎么办？

怎么维护这些漂亮的原始设计

和实际数据库表结构的一致性呢？

如果手工维护，工作量巨大而且不能保证完全的
一致性

这个例子显示了如何从数据库中抽取

所需要的元素生成数据库文档

这个方案是众多方案中的一个，比较灵活

它结合了SchemaSpy、Ant 和 Javadoc

通过java Ant的任务调度调用了SchemaSpy

并传递了一些连接数据库必需的参数

如计算机名称或ip地址，端口号，用户名和密码
等等

最后生成html格式的数据库文档

这些文档反映了当前开发时刻最新的数据词典

同样的，这些配置脚本可以部署到持续集成的
流程中

每次代码变更进行重新构建的时候

就可以随时完成一次文档更新

确保数据库文档对所有开发者都是最新的，一致
的

用户的修改可以马上传递给所有的开发人员

下面再看一个代码文档化的例子

对程序员来说，代码注释是他们最常写的文档

因为这些注释无论是对开发者自己

还是对别人，都是非常有价值的

如何充分利用这些分散在代码各个角落的注释

是文档自动化的一个关注重点

俗话说，巧妇难为无米之炊

如果连注释都没有

自动化程度再高的工具也无法无中生有的生成文
档

因此，我们要鼓励程序员要多写注释，规范的写
注释

然后才有可能通过文档生成工具快速生成相关的
文档

节约程序员的时间，保持文档和代码的一致性

除了常规的行注释和块注释之外

Java和.net都有自己的更全面的注释格式

Java用javadoc，.net用Xml注释

其中xml注释也叫三斜杠注释

后面跟着xml注释的标签

.net编译器在编译的时候可以提取出这些注释项

生成xml文件，然后借助其他的处理工具

可以生成pdf，doc或html等各种各样易于阅读的
文档

这里给出了利用doxgen生成代码文档的脚本和示
例

这些脚本可以放到持续集成的流程中自动执行

到目前为止，你可能一直在想

自动生成技术文档固然不错

但是最头疼的可能是创建用户文档

在编写用户文档的时候

我们发现大量的时间都浪费在文档的复制粘贴上

对文档的排版更是麻烦

辛辛苦苦排好的文档

很快就因为软件的微小更新而不得不

从头到尾逐项检查和修改

以维持用户文档和软件之间的一致性

如果我们有了遗漏，交付之后用户的不满就可想
而知了

在这个示例当中，通过综合运用Ant、一个
DocBook XSL 文件

和 XSL样式对象来生成pdf格式的用户文件

这里使用XML和XSL将内容和格式隔离开

将文档所需要的文字，图片，甚至是视频片段等

保存在某个位置，形成一个单一的内容源

文档的局部更改就直接去单一源那里修改对应的
内容

不用关心其他内容

如果用户对格式不满意，只需要修改XSL格式模
板就可以了

好，文档自动化我们就讨论到这里，谢谢大家