当前课程知识点：软件工程与软件自动化 > 第五章 软件自动化技术 > 5.3 文档自动化 > 文档自动化视频
嗨，大家好
今天我们来讨论文档自动化的话题
说到文档，没有人会否认文档的重要性
但是对于程序员来说，写文档真的是一件不爱干
却不得不干的事情
前面我们在讨论方法论的时候也说过
重型开发方法的一个重要特征就是中间产物很多
这个中间产物，主要就是指文档
所以敏捷方法强调，文档只写必要的文档
多余的文档对客户对开发人员都是一种负担
一个逼着看文档，一个逼着写文档，都不好受
从程序员角度来说，不爱写文档主要是觉得
写了白写，没人爱看
进一步分析，为什么没人爱看
是因为文档总过时，看了文档也和代码对不上
于是就不爱看了
那么如何解决这个问题呢？
团队管理者应该积极引入文档自动化技术
简化文档生成过程
减轻开发人员的文档编写负担
更重要的是，通过文档自动化技术
可以维持文档与设计模型和代码之间的一致性
保证文档的精确性和时效性
开发人员只需要维护单一源头
也就是设计模型或者代码
需要更新文档的时候，可以一键生成最新的文档
在早期软件开发活动中，设计和编码是分开的
由不同的人员使用不同的设计开发工具，各做各
的
程序员在编码的时候很容易就偏离设计
现在呢，大的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格式模
板就可以了
好，文档自动化我们就讨论到这里，谢谢大家
-1.1 软件工程的前生今世
--开篇阅读
--授课视频
-第一章 软件工程基础--1.1 软件工程的前生今世
-1.2 万变不离其宗
--授课视频1/3
--授课视频2/3
--授课视频3/3
-第一章 软件工程基础--1.2 万变不离其宗
-1.3 唯一不变的是变化
--授课视频1/3
--授课视频2/3
--授课视频3/3
--外部链接
-第一章 软件工程基础--1.3 唯一不变的是变化
-1.4 亡羊补牢为时不晚
--授课视频1/2
--授课视频2/2
-第一章 软件工程基础--1.4 亡羊补牢为时不晚
-扩展阅读与话题讨论
--扩展阅读
--话题讨论
-2.1 方法论来源于恐惧
--授课视频
-第二章 敏捷开发--2.1 方法论来源于恐惧
-2.2 敏捷是什么
--授课视频
-第二章 敏捷开发--2.2 敏捷是什么
-2.3 典型敏捷开发方法
--XP敏捷开发方法
-第二章 敏捷开发--2.3 典型敏捷开发方法
-2.4 敏捷不是万能药
--授课视频
-第二章 敏捷开发--2.4 敏捷不是万能药
-专家谈敏捷
-扩展阅读与话题讨论
--外部链接
--话题讨论
-3.1 面向对象核心概念和基本特性
-第三章 OO与UML--3.1 面向对象核心概念和基本特性
-3.2 面向对象设计基本原则
-第三章 OO与UML--3.2 面向对象设计基本原则
-3.3 通用职责分配模式(GRASP)
--通用职责分配模式
-3.3 通用职责分配模式(GRASP)--作业
-3.4 从重构到模式
--模式和设计模式
-第三章 OO与UML--3.4 从重构到模式
-3.5 使用UML设计面向对象系统
--UML综述
-第三章 OO与UML--3.5 使用UML设计面向对象系统
-3.6 主要UML模型图绘制技巧
--UML用例图
--UML类图
-第三章 OO与UML--3.6 主要UML模型图绘制技巧
-扩展阅读与话题讨论
--设计模式有毒么？
--话题讨论
-4.1 案例简介
--书籍参考
--案例说明
-4.2 对象模型之一
--授课视频1/2
--授课视频2/2
-第四章 对象模型分析--4.2 对象模型之一
-4.3 对象模型之二
--授课视频1/2
--授课视频2/2
-第四章 对象模型分析--4.3 对象模型之二
-4.4 对象模型之交互
--授课视频
-第四章 对象模型分析--4.4 对象模型之交互
-扩展阅读与话题讨论
--图书推荐
--话题讨论
-5.1 软件自动化概述
--软件自动化概述
-第五章 软件自动化技术--5.1 软件自动化概述
-5.2 典型自动化方法和工具
-第五章 软件自动化技术--5.2 典型自动化方法和工具
-5.3 文档自动化
--文档自动化视频
-第五章 软件自动化技术--5.3 文档自动化
-5.4 测试自动化
--测试自动化视频
-第五章 软件自动化技术--5.4 测试自动化
-专家访谈
-扩展阅读与话题讨论
--话题讨论
-6.1 持续集成
-第六章 CI/CD与DevOps--6.1 持续集成
-6.2 持续交付和部署
-第六章 CI/CD与DevOps--6.2 持续交付和部署
-6.3 DevOps
-第六章 CI/CD与DevOps--6.3 DevOps
-专家访谈
-扩展阅读与话题讨论
--DevOps专题
--话题讨论
-7.1 质量和质量保证
--授课视频
-第七章 软件质量保证--7.1 质量和质量保证
-7.2 软件质量模型
--授课视频
-第七章 软件质量保证--7.2 软件质量模型
-7.3 SQA组织与职责
--授课视频
-第七章 软件质量保证--7.3 SQA组织与职责
-7.4 全面软件质量管理
--授课视频
-第七章 软件质量保证--7.4 全面软件质量管理
-专家访谈
--专家访谈
-扩展阅读与话题讨论
--外部链接
--话题讨论
-8.1 软件过程综述
--授课视频
-第八章 软件过程改进--8.1 软件过程综述
-8.2 软件过程改进
--授课视频
-第八章 软件过程改进--8.2 软件过程改进
-8.3 能力成熟度模型
--授课视频
-第八章 软件过程改进--8.3 能力成熟度模型
-8.4 过程改进标准框架
--授课视频
-第八章 软件过程改进--8.4 过程改进标准框架
-扩展阅读与话题讨论
--话题讨论
-9.1软件复用综述
--授课视频
-第九章 软件复用--9.1软件复用综述
-9.2 软件构件技术
--授课视频
-第九章 软件复用--9.2 软件构件技术
-9.3 软件复用实施
--授课视频
-第九章 软件复用--9.3 软件复用实施
-9.4 微服务架构
--授课视频
-第九章 软件复用--9.4 微服务架构
-扩展阅读与话题讨论
--微服务扩展
--话题讨论
-文档提交处--文档提交
