介绍

现在 IT 开发人员比以往任何时候都更加关注测试的重要性，没有经过良好测试的代码更容易出问题。在极限编程中，测试驱动开发已经被证明是一种有效提高软件质量的方法。在测试驱动的开发方式中，软件工程师在编写功能代码之前首先编写测试代码，这样能从最开始保证程序代码的正确性，并且能够在程序的每次演进时进行自动的回归测试。测试对于软件产品的成败起着至关重要的作用，在极限编程领域，甚至有人提议任何未经测试的代码都应该自动从发布的产品中删除。作者并不确信这个观点是正确的，但是测试本身的质量确实是一个需要高度关注的问题。测试的覆盖率是测试质量的一个重要指标，我们需要工具来帮助我们进行对软件测试覆盖的考察。

EclEmma 就是这样一个能帮助开发人员考察测试覆盖率的优秀的 Eclipse 开源插件。EclEmma 在覆盖测试领域是如此的优秀，以致于它在过去不久的 2006 年成为了 Eclipse Community Awards Winners 决赛选手。虽然最后 Eclipse Checkstyle Plugin 取得了 Best Open Source Eclipse-based Developer tool 的称号，但我们也可以由此看到 EclEmma 对开发人员的帮助是巨大的（Eclipse Community Award 的具体信息可以参阅 参考资源）。

提到 EclEmma 首先就要说到著名的 Java 覆盖测试工具 Emma。Emma 是一个在 SourceForge 上进行的开源项目（参阅 参考资源）。从某种程度上说，EclEmma 可以看作是 Emma 的一个图形界面。在本文的参考文献中，可以看到专门讲述使用 Emma 的技术文章。

Emma 的作者开发 Emma 之初，程序员已经有了各种各样优秀的开源 Java 开发工具。举例来说，我们有优秀的集成开发环境 Eclipse，有开源的 JDK，有单元测试工具 JUnit，有 Ant 这样的项目管理工具，我们还可以用 CVS 或 SubVersion 来进行源代码版本的维护。当时看来，也许唯一缺少的就是一个开源的覆盖测试工具了。Emma 就是为了填补这项空白而生的。现在的情况已经和 Emma 诞生的时候不一样的。时至今日，我们已经有了不少的覆盖测试工具。例如 Coverlipse 是一个基于 Eclipse 的覆盖测试插件。其他还有 Cobertura，Quilt 和 JCoverage 等。但是 Emma 具有一些非常优秀的特性使得它更适合被广泛的使用。和 Coverlipse 等工具比起来，Emma 是开源的，同时它对应用程序执行速度的影响非常小。

EclEmma 的出现弥补了 Emma 用户一个大的遗憾 ---- 缺乏图形界面以及对集成开发环境的支持。将 Eclipse 和 Emma 这两个在各自领域最为优秀的工具结合起来，这就是 EclEmma 为我们提供的。接下来，我们就要在后续章节中和读者朋友一起看看 EclEmma 为开发人员提供了什么。

回页首

安装 EclEmma 插件

安装 EclEmma 插件的过程和大部分 Eclipse 插件相同，我们既可以通过 Eclipse 标准的 Update 机制来远程安装 EclEmma 插件（图 1），也可以从站点（参阅 参考资源）下载 zip 文件并解压到 eclipse 所在的目录中。

不管采用何种方式来安装 EclEmma，安装完成并重新启动 Eclipse 之后，工具栏上应该出现一个新的按钮：

回页首

使用 EclEmma 测试 Java 程序

为了实验 EclEmma 的特性，我们首先在 Eclipse 的 Workspace 中建立一个名称为 test.emma 的新 Java 项目。接下来，我们在其中建立一个 HelloWorld 类，其代码如下所示：

            package test.emma;
            public class HelloWorld {
            /**
            * @param args
            */
            public static void main(String[] args) {
            int rand = (int) (Math.random()*100);
            if(rand%2==0){
            System.out.println( "Hello, world! 0");
            }
            else
            System.out.println("Hello, world! 1");
            int result = rand%2==0? rand+rand:rand*rand;
            System.out.println(result);
            }
            }
            

接下来，我们通过 EclEmma 运行 HelloWorld.main() 函数。

执行完毕之后，我们正在编辑 HelloWorld.java 的窗口将会变成如下所示：

在 Java 编辑器中，EclEmma 用不同的色彩标示了源代码的测试情况。其中，绿色的行表示该行代码被完整的执行，红色部分表示该行代码根本没有被执行，而黄色的行表明该行代码部分被执行。黄色的行通常出现在单行代码包含分支的情况，例如 图 4 中的 16 行就显示为黄色。由于程序中有一个随机确定的分支，因此读者的窗口可能与这里稍有不同（11 行或者 14 行中有且只有一个红色的行）。

除了在源代码编辑窗口直接进行着色之外，EclEmma 还提供了一个单独的视图来统计程序的覆盖测试率。

EclEmma 提供的 Coverage 视图能够分层的显示代码的覆盖测试率，图 5 中的信息表明我们对 HelloWorld 的一次运行覆盖了大约 68.6% 的代码。

想在一次运行中覆盖所有的代码通常比较困难，如果能把多次测试的覆盖数据综合起来进行察看，那么我们就能更方便的掌握多次测试的测试效果。EclEmma 提供了这样的功能。现在，让我们重复数次对 HelloWorld 的覆盖测试。我们注意到 Coverage 视图总是显示最新完成的一次覆盖测试。事实上，EclEmma 为我们保存了所有的测试结果。接下来，我们将通过 Coverage 视图的工具按钮来结合多次覆盖测试的结果。

当我们多次运行 Coverage 之后，我们可以单击 图 6 所示工具栏按钮。之后，一个对话框将被弹出以供用户选择需要合并的覆盖测试。

在合并完成之后，我们可以观察到 Java 编辑器和 Coverage 视图中都显示了合并之后的结果：

图 8 中，我们可以看到，通过多次运行覆盖测试，最终我们的代码达到了 91.4% 的测试覆盖率。有趣的是，图中第三行代码被标记为红色，而此行代码实际上是不可执行的。奥妙在于，我们没有生成任何 HelloWorld 类的实例，因此缺省构造函数没有被调用，而 EclEmma 将这个特殊代码的覆盖状态标记在类声明的第一行。

回页首

EclEmma 的高级特性

如果 EclEmma 只能测试 Java Application 的测试覆盖率，那么它相对命令行版本的 Emma 来说，提供的增强就不多了。相反，EclEmma 提供了很多与 Eclipse 紧密结合的功能。它不仅能测试 Java Application，还能计算 JUnit 单元测试，对 Eclipse 插件测试的覆盖率。从 图 9 中我们可以看到 EclEmma 目前支持四种类型的程序。

为了了解 EclEmma 是如何获得覆盖测试数据的，我们需要先对 Emma 有初步的了解。通常代码覆盖测试工具都需要对被执行的代码进行修改。而 Emma 提供了两种方式来完成这件事。

1. 预插入模式：对程序进行测量之前，需要采用 Emma 提供的工具对 class 文件或者 jar 文件进行修改。修改完成之后的代码可以立刻被执行。覆盖测试的结果将会被存放到指定的文件中。
2. 即时插入模式：即时插入模式不需要事先对代码进行修改。相反，对代码的修改是通过一个 Emma 定制的 Class loader（类载入器）进行的。这种方式的优点很明显，我们不需要对 class 或者 jar 文件进行任何修改。缺点是我们为了获得测试的结果，需要用 Emma 提供的命令 emmarun 来执行 Java 应用程序。

使用即时插入模式的优点很明显：class 文件和 jar 文件不会被修改。而预插入模式的应用范围更为广泛，对于某些需要嵌入到框架中运行的代码来说（例如 EJB），我们只能使用预插入模式。EclEmma 仅仅使用了 Emma 的预插入模式来工作，不过 EclEmma 缺省会在临时目录中创建 class 文件和 jar 文件的副本来进行修改，因此在 workspace 中 class 和 jar 文件仍然保持原样。虽然听上去很好，但是由于需要修改 classpath 来使用修改过的 class 和 jar 文件，对于不能修改 classpath 的应用（例如 Eclipse RCP 和 JUnit Plugin Test）来说，我们还是只能选择修改 workspace 中的 class 文件和 jar 文件。对于 Java Application 和 JUnit 类型的覆盖测试，我们可以在配置对话框中选中“In-place instrumentation”项来指定直接修改 Workspace 中的 .class 文件和 .jar 文件。

回页首

结论

本文通过一个简单的例子介绍了使用 EclEmma 进行覆盖测试的基本过程。EclEmma 允许软件工程师方便的考察测试的覆盖率，并能将测试结果以直观、简洁的方式展现给开发人员。

参考资料

• developerWorks 文章“使用 EMMA 测量测试覆盖率”：介绍了 EclEmma 的核心 Emma 的使用方法。
  
  
• developerWorks 文章“怎样使用 JUnit Framework 进行单元测试的编写”：一篇介绍 JUnit 的优秀文章。
  
  
• developerWorks 文章“TestNG 使 Java 单元测试轻而易举”：介绍了一个比 JUnit 更新的测试框架 TestNG。
  
  
• developerWorks 文章“追求代码质量: 不要被覆盖报告所迷惑”：覆盖测试也有其局限性，通过本文可以理解即使达到了 100% 的覆盖率，bug 也仍然可能出现。
  
  
• developerWorks 文章“持续测试: 将错误扼杀在摇篮之中”：介绍了一种更高效的进行单元测试的有趣技术。
  
  

• 下载 EclEmma 安装文件。
  
  
• 访问 Emma 的官方站点。

• 通过 测试驱动开发社区，您可以了解更多关于测试驱动开发的信息。
  
  
• 了解关于 Eclipse Community Award 的具体信息。
  
  

关于作者

		甘志，IBM 中国软件实验室（CSDL BJ）China Emerging Technology Institute 成员，主要研究方向为 UML、Model driven development 和 SOA。他在上海交通大学计算机系获得网络安全方向博士学位，期间发表了多篇论文和技术书籍。你可以通过 ganzhi@cn.ibm.com 联系他。

0. 序言
为代码写注释一直是大多数程序员有些困扰的事情。当前程序员都能接受为了程序的可维护性、可读性编码的同时写注释的说法，但对哪些地方应该写注释，注释如何写，写多少等这些问题，很多程序员仍然没有答案。更头痛的是写文档，以及维护文档的问题，开发人员通常可以忍受编写或者改动代码时编写或者修改对应的注释，但之后需要修正相应的文档却比较困难。如果能从注释直接转化成文档，对开发人员无疑是一种福音。而doxygen就能把遵守某种格式的注释自动转化为对应的文档。

Doxygen是基于GPL的开源项目，是一个非常优秀的文档系统，当前支持在大多数unix（包括linux），windows家族，Mac系统上运行，完全支持C++, C, Java, IDL（Corba和Microsoft 家族）语言，部分支持PHP和C#语言，输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目（包括前两篇文章介绍的log4cpp和CppUnit）都使用了doxygen文档系统。而国内的开发人员却使用的不多，这里从开发人员使用的角度介绍这个工具，使开发人员用最少的代价尽快掌握这种技术，并结合这个工具探讨如何撰写注释的问题。以下以linux下的C++语言为例进行介绍，以下讨论基于doxygen1.3.3。

1. doxygen使用步骤
由于只是工具的使用，这里不介绍它的原理，直接从使用步骤开始。Doxygen的使用步骤非常简单。主要可以分为：
 1）第一次使用需要安装doxygen的程序
 2）生成doxygen配置文件
 3）编码时，按照某种格式编写注释
 4）生成对应文档
doxygen的安装非常简单， linux下可以直接下载安装包运行即可，下载源代码编译安装也是比较通用的编译安装命令。请参考其安装文档完成安装。

Doxygen在生成文档时可以定义项目属性以及文档生成过程中的很多选项，使用下面命令能够产生一个缺省的配置文件：
doxygen -g  [配置文件名]
可以根据项目的具体需求修改配置文件中对应的项，具体的修改过程在下面介绍。修改过的配置文件可以作为以后项目的模板。

让doxygen自动产生文档，平常的注释风格可不行，需要遵循doxygen自己的格式。具体如何写doxygen认识的注释在第3节详细介绍。

OK，代码编完了，注释也按照格式写好了，最后的文档是如何的哪？非常简单，运行下面的命令，相应的文档就会产生在指定的目录中。
  doxygen [配置文件名]

需要注意的是doxygen并不处理所有的注释，doxygen重点关注与程序结构有关的注释，比如：文件、类、结构、函数、变量、宏等注释，而忽略函数内变量、代码等的注释。

2. doxygen配置文件
doxygen配置文件的格式是也是通常的unix下配置文件的格式：注释'#'开始；tag = value [,value2…]；对于多值的情况可以使用 tag += value [,value2…]。

对doxygen的配置文件的修改分为两类：一种就是输出选项，控制如何解释源代码、如何输出；一种就是项目相关的信息，比如项目名称、源代码目录、输出文档目录等。对于第一种设置好后，通常所有项目可以共用一份配置，而后一种是每个项目必须设置的。下面选择重要的，有可能需要修改的选项进行解释说明，其他选项在配置文件都有详细解释。

TAG 缺省值 含义
PROJECT_NAME  项目名称
PROJECT_NUMBER  可以理解为版本信息
OUTPUT_DIRECTORY  输出文件到的目录，相对目录（doxygen运行目录）或者绝对目录
INPUT  代码文件或者代码所在目录，使用空格分割
FILE_PATTERNS *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp *.h++ *.idl *.odl 指定INPUT的目录中特定文件，如：*.cpp *.c *.h
RECURSIVE NO 是否递归INPUT中目录的子目录
EXCLUDE  在INPUT目录中需要忽略的子目录
EXCLUDE_PATTERNS  明确指定的在INPUT目录中需要忽略的文件，如：FromOut*.cpp
  
OUTPUT_LANGUAGE English 生成文档的语言，当前支持2、30种语言，国内用户可以设置为Chinese
USE_WINDOWS_ENCODING YES（win版本）
NO（unix版本） 编码格式，默认即可。
EXTRACT_ALL NO 为NO，只解释有doxygen格式注释的代码；为YES，解析所有代码，即使没有注释。类的私有成员和所有的静态项由EXTRACT_PRIVATE和 EXTRACT_STATIC控制
EXTRACT_PRIVATE NO 是否解析类的私有成员
EXTRACT_STATIC NO 是否解析静态项
EXTRACT_LOCAL_CLASSES YES 是否解析源文件（cpp文件）中定义的类
SOURCE_BROWSER NO 如果为YES，源代码文件会被包含在文档中
INLINE_SOURCES NO 如果为YES，函数和类的实现代码被包含在文档中
ALPHABETICAL_INDEX NO 生成一个字母序的列表，有很多类、结构等项时建议设为YES
GENERATE_HTML YES 是否生成HTML格式文档
GENERATE_HTMLHELP NO 是否生成压缩HTML格式文档（.chm）
GENERATE_LATEX YES 是否乘车latex格式的文档
GENERATE_RTF NO 是否生成RTF格式的文档
GENERATE_MAN NO 是否生成man格式文档
GENERATE_XML NO 是否生成XML格式文档
  

3. doxygen注释
3.1 注释风格
下面是工作量最大部分，安装doxygen格式写注释。通常代码可以附上一个注释块来对代码进行解释，一个注释块由一行或者多行组成。通常一个注释块包括一个简要说明（brief）和一个详细说明（detailed），这两部分都是可选的。可以有多种方式标识出doxygen可识别的注释块。
1）JavaDoc类型的多行注释。
/**
 *  ….text….
 */
2）QT样式的多行注释。
/*!
….text….
 */
3） /// …text….
4） //! …text….
简要说明有多种方式标识，这里推荐使用@brief命令强制说明，例如：
/**
 * @brief [some brief description ]
 *      [ brief description more. ]
 *
 * [some more detailed description…]
 */
以上这些注释格式用来对紧跟其后的代码进行注释。doxygen也允许把注释放到代码后面，具体格式是放一个'<'到注释开始部分。例如：
int var1 ; /**< ….text…. */
int var2; ///< ….text….

注释和代码完全分离，放在其他地方也是允许的，但需要使用特殊的命令加上名称或者声明进行标识，比如：class、struct、union、enum、fn、var、def、file、namespace、package、interface（这些也就是doxygen关注的注释类型）。这里不推荐使用，建议注释尽量放在代码前后。具体使用方式参见doxygen手册。

3.2 doxygen常用注释格式
通常的选择上面的一、两种注释风格，遇到头文件中各种类型定义，关键变量、宏的定义，在其前或者后使用 @brief 定义其简要说明，空一行后继续写其详细的注释即可。

对函数的注释，是比较常常需要注释的部分。除了定义其简要说明以及详细注释，还可以使用param命令对其各个参数进行注释，使用return命令对返回值进行注释。常见的格式如下：
/**
 *@brief func's brief comment.
 *
 * Some detailed comment.
 *@param a [param a 's comment.]
 *@param b [param b 's comment.]
 *@exception std::out_of_range [exception's comment.]
 *@return [return's comment.]
 */
int func1(int a, int b);

进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。如何对这个概念进行注释？doxygen提供了group的概念，生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个group。
/** [group_name] [brief group description ]
 * detailed group description ]
 * @{
*/
code
/** @} */
group中的代码可以有自己的注释。单纯定义一个模块，去除{ 和}命令即可。任何其他代码项（比如类、函数、甚至文件）如果要加入到某个模块，可以在其doxygen注释中使用ingroup命令即可。Group之间使用ingroup命令，可以组成树状关系。
/** @file util.cpp
* @ingroup [group_name]
 * @brief file's brief info.
 */
把多个代码项一起添加到某个模块中可以使用addtogroup命令，格式和defgroup相似。

对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式：
//@{
/** Comments for all below code. */
code…
//@}
对这种组进行命名可以使用name命令。此时中间代码可以有自己的注释。如：
/** @name group_name
 * description for group.
 */
//@{
code…
//@}

3.3 doxygen常用注释命令
doxygen通过注释命令识别注释中需要特殊处理的注释，比如函数的参数、返回值进行突出显示。上面也提到了一些注释命令（如：brief、param、return、以及group相关的命令），下面对其他一些常用的注释命令进行解释说明。
@exception <exception-object> {exception description} 对一个异常对象进行注释。
@warning {warning message } 一些需要注意的事情
@todo { things to be done }  对将要做的事情进行注释
@see {comment with reference to other items } 一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接。
@relates <name> 通常用做把非成员函数的注释文档包含在类的说明文档中。
@since {text} 通常用来说明从什么版本、时间写此部分代码。
@deprecated
@pre { description of the precondition } 用来说明代码项的前提条件。
@post { description of the postcondition } 用来说明代码项之后的使用条件。
@code 在注释中开始说明一段代码，直到@endcode命令。
@endcode 注释中代码段的结束。

到此为止，常用的doxygen的注释格式讨论完毕，我们能够按照一定的格式撰写doxygen认识的注释，并能够使用doxygen方便快捷的生成对应的文档，不过注释中应该写些什么，如何撰写有效的注释可能是困扰开发人员的一个更深层次的问题。

4. 注释的书写
注释应该怎么写，写多还是写少。过多的注释甚至会干扰对代码的阅读。写注释的一个总的原则就是注释应该尽量用来表明作者的意图，至少也应该是对一部分代码的总结，而不应该是对代码的重复或者解释。对代码的重复或者解释的代码，看代码可能更容易理解。反映作者意图的注释解释代码的目的，从解决问题的层次上进行注释，而代码总结性注释则是从问题的解答的层次上进行注释。

推荐的写注释的过程是首先使用注释勾勒出代码的主要框架，然后根据注释撰写相应的代码。对各种主要的数据结构、输出的函数、多个函数公用的变量进行详细地注释。对代码中控制结构，单一目的的语句集进行注释。下面是一些写注释时需要注意的要点：
  避免对单独语句进行注释；
  通过注释解释为什么这么做、或者要做什么，使代码的读者可以只阅读注释理解代码；
  对读者可能会有疑问的地方进行注释；
  对数据定义进行注释，而不是对其使用过程进行注释；
  对于难于理解的代码，进行改写，而不要试图通过注释加以说明；
  对关键的控制结构进行注释；
  对数据和函数的边界、使用前提等进行注释；

5. 参考资料
 1. doxygen homepage
 http://www.stack.nl/~dimitri/doxygen/

 2. doxygen manual
 http://www.stack.nl/~dimitri/doxygen/manual.html

 3. Code Complete: A Practical Handbook of Software Construction. Redmond, Wa.: Microsoft Press, 880 pages, 1993. ISBN: 1-55615-484-4.
 
 4. 简介doxygen
 http://www.stack.nl/~dimitri/doxygen/doxygen_intro_cn.html
 
 5. 10 Minutes to document your code
 http://www.codeproject.com/tips/doxysetup.asp

 6. 使用doxygen
 http://www.csdn.net/Develop/article/16%5C16383.shtm

 
6. 关于作者
mounton @ {www.ihere.org} 当前关注于网络安全产品的开发、研究；软件开发过程等方面。您可以通过mount0n@yahoo.com和他联系。