《让开发自动化化一键通》由会员分享，可在线阅读，更多相关《让开发自动化化一键通（17页珍藏版）》请在金锄头文库上搜索。
1、让开发自动化: 文档化一键通自动生成开发人员和用户文档Paul Duvall, CTO, Stelligent IncorporatedPaul Duvall 是 Stelligent Incorporated 的 CTO，该公司是一家咨询公司，在帮助开发团队优化 Agile 软件产品方面被认为是同行中的翘楚。他是 Addison-Wesley Signature 系列书籍 Continuous Integration: Improving Software Quality and Reducing Risk （Addison-Wesley，2007 年）的作者之一。他对 UML 2 Tool
2、kit （Wiley，2003 年）和 No Fluff Just Stuff Anthology （Pragmatic Programmers，2007 年）也有贡献。简介： 项目的文档化通常都是交付软件产品时不可避免的难题。但是想象一下如果仅需单击一个按钮就能够生成文档呢？在本期的 让开发自动化 中，自动化专家 Paul Duvall 阐述了如何运用开源工具自动生成统一建模语言（Unified Modeling Language，UML）图、构建图、实体关系图（entity-relationship diagram，ERD）乃至用户文档。查看本系列更多内容本文的标签： ant, java_
3、技术, 应用开发, 开放源码标记本文！发布日期： 2008 年 6 月 24 日 级别： 初级 原创语言： 英文 访问情况 ： 4527 次浏览 评论： 0 (查看 | 添加评论 - 登录) 平均分 (6个评分)为本文评分很少有软件开发人员愿意为他们的软件开发项目编写文档。然而，除非您永远不想完成您的项目，或者您永远独立进行软件开发，又或者您没有用户 这对一个项目来说可不是一个好现象，否则您就需要用一种方式来向别人交待您的软件的用途。有些开发者误解了 Agile Manifesto 的 “可运行的软件 优于全面的文档” 的说法，以为根本不需要 任何的文档资料（请参阅 参考资料）。另一方面，多余
4、的文档对用户或其他开发人员来说也是一个负担。我通常寻找一种中间办法。您猜对了：本文将向您展示如何运用 自动化来简化项目文档的生成过程，从而减轻这方面的负担。关于本系列作为开发人员，我们致力于为用户自动化流程；但许多开发人员疏忽了自动化我们自己的开发流程的机会。为此，我们编写了 让开发自动化 系列文章，专门探讨软件开发流程自动化的实践应用，为您介绍 何时以及 如何成功应用自动化。按照我的经验，有两个关键性的问题制约着软件开发的文档化。第一个问题，似乎没有人会去阅读文档。第二个常见问题就是几乎是在编写文档的同时，它就已经过时了。这两个问题是有着因果联系的：如果文档总是保持最新，那么人们就更有可能去
5、阅读它。自动化生成文档便可以解决这两个问题，它可以保持文档的时效性，从而使它对您的软件用户更加有用。自动化也可能对其他类型的文档有利，但在本文中我将着重阐述如何让那些令人痛苦的文档化任务自动化（请参阅 参考资料查找下面列表中提到的工具的链接）： 使用 UMLGraph 生成当前源代码的 UML图。 使用 SchemaSpy 创建 实体关系图（ERD），归档数据库中的表格和关系。 使用 Grand 生成构建目标以及它们之间的关系的 Ant 构建图。 使用 Doxygen 生成 源代码文档。 使用 DocBook 制作 用户文档。 我将使用一般的方法阐述以下内容：1. 描述手动执行每一项任务遇到的
6、问题。 2. 呈现一个结合使用 Apache Ant 和相关的文档 / 图表生成工具实现自动化的例子。 3. 展示一个基于代码示例的脚本生成文档的图象。 和本系列前面的文章一样，文中所有示例都使用可免费获得的开源工具，您可以在自己的项目中使用。有些工具（例如，UMLGraph 和 Grand）会使用一个附带的 GraphViz 工具，该工具要用到一个由特定工具生成的 .dot 文件。将代码反向工程到 UML 中我曾遇到过一些拥有十分美观的 UML 图的项目 在项目的初始阶段。问题是，在某种特殊情况下，技术负责人无法使模型与源代码同步。或者需要将宝贵的时间浪费在将源代码 手动反向工程到模型中。这
7、两种情况都不尽如人意。如果模型无法如实地展示签入到版本控制库中的代码，那么这个 UML 图构造的再美观也毫无意义。如果您没有根据实际的代码制定决策，那么您可能就要面临随之而来的很多问题。您可以在构建过程中生成图示，并建立一个持续集成（Continuous Integration，CI）环境来即时地（或定期地）创建图示。这样您就能够制作出有益于决策、易于创建且始终反映最新情况的图示了。清单 1 使用 Ant、UMLGraph 以及 Graphviz 对源代码进行文档化 :清单 1. 使用 UMLGraph 文档化工具的 Ant 脚本 清单 1 中，我结合使用 UMLGraph 和 Javadoc
8、 在 Javadoc HTML 报告内部生成一些基本的 UML 类图。为了自定义展示在每一个类图中的信息，调用 UmlGraphDoc时，我传递了如下属性：使用 GraphViz 制图要正常使用 UMLGraph，您必须先安装 Graphviz 工具（请参阅 参考资料，并且计算机的系统路径中必须包含 Graphviz .dot 文件。 -attribute 为类显示字段。 -enumeration 展示不同的枚举。 -enumconstant 为枚举展示可能的值。 -operation 为类显示 Java 方法。 -qualify 显示完全限定类名。 -type 显示参数数据类型和返回类型 -
9、visibility 展示字段和方法修改语：public、protected、private或 default。 图 1 展示了用 UMLGraphshows 生成到 HTML 中的 LoginDaoImpl类及其关系的 UML 图例：图 1. 用 UMLGraph 生成的 UML 图请 单击此处查看完整图形。UMLGraph 能够生成更复杂的关系和其他细节。但是，即便是这个简单例子中极其基本的 UML 类图，就已经提供了相当多的信息。它也可以根据当前的代码库快捷、形象地展示软件。它防止了 “代码 应该是这样的” 这种陈述方式，并且有益于做出更好的决策（关于描述了多种可以自定义 UMLGrap
10、h 输出的属性的链接，请参阅 参考资料）。回页首数据库文档化自动创建最新的 UML 图将使您获益良多，同样，自动地可视化表示数据库也可以让您受益匪浅。实体关系图（ERD）是实现数据库可视化的最流行的图示类型。大多数创建 ERD 的工具（例如，ERWinfor）都需要手动生成 ERD。虽然我将要示范的工具 SchemaSpy 无法与现存的一些更复杂的工具媲美，但是它能够提供数据库的高级 ERD 视图 以及约束、关系等。而且，通过自动构建来运行它，您就可以轻松地从您的版本控制库中检查数据定义语言（Data Definition Language，DDL）的最新显示。清单 2 中的 Ant 脚本使用
11、 SchemaSpy 工具来创建 Javadoc 格式的文件：清单 2. 结合使用 SchemaSpy、Ant 和 Javadoc 清单 2 使用 javaAnt 任务调用 SchemaSpy，传递了很多属性： -t 为数据库类型（有效值为 mysql、ora、db2，等等。) -host 为托管数据库的计算机名。 -port 为数据库 URL 的端口数。 -u 为数据库用户名。 -p 为数据库密码。 -cp 为类路径（用于指示数据库驱动程序 JAR 文件的位置）。 -o 为输出目录的位置。 这些 SchemaSpy 的命令行属性用于生成显示 ERD 的 HTML 文件，如图 2 所示：图 2. 用 SchemaSpy 和 Ant 创建的 ERD通过结合使用多种
