将代码注释转换为过程规范( 六 ) _代码注释

? 我们根据准确率和召回率（信息检索任务的标准指标）来衡量有效性，例如将 Javadoc 注释翻译为过程规范。
? 准确率衡量正确输出相对于缺失和错误输出的比例。当 Jdoctor 产生与预期规范匹配的规范时，输出正确（C）。当 Jdoctor 不产生任何规范时，输出丢失（M）。当 Jdoctor 在没有预期的规格（W1）或与预期的规格不匹配的规格（W2）产生规格时，输出错误。准确率定义为正确输出数与输出总数之间的比率：

文章插图

? 召回率衡量工具产生的期望输出的比例，它定义为正确输出的数量与期望输出的总数之间的比率：

文章插图

? 我们的评估保守地认为部分正确的翻译是错误的。例如，如果注释为“@throws Exception如果x为负或y为空”，则翻译“ x <0”被视为错误。
5.1 实验设置为了进行评估，我们选择了 6 个维护良好的开源 Java 系统（请参阅表 1）。对于每个系统，我们（i）丢弃没有文档或文档数量有限的类，即 Javadoc 注释少于 5 个，以及（ii）忽略注释了从java.lang.Object继承的方法、getter 和 setter（其名称为方法的注释）以“ get”或“ set”开头）。表 1 中的“文档班级”列报告了满足每个学科这些条件的班级数。
? 然后，我们选择并手动分析了至少 10％的已记录类和方法：分别在“已分析类”和“已分析方法”列中。为此，我们应用了 PPS（概率正比于规模）抽样方法，选择每个类别的概率与该类别中的方法数量成正比。对于每个选定类中的每个分析方法，我们手动确定其基本事实-将 Javadoc 注释正确转换为可执行方法规范。为此，我们阅读了用英语表达的 Javadoc 注释，并编写了与每个@ param、@ return、@ throws和@exception标记相对应的可执行规范。至少有两位作者独立审查了每种翻译。
? 有时，与 Javadoc 标记对应的文本不能表示为可执行规范。一个示例是“如果在读取文件时遇到问题，则@throws IOException” 。对于此类注释，我们不希望 Jdoctor 产生任何输出。我们丢弃了不包含任何可转换为可执行规范的注释的类，即不属于已分析类的列表。这给我们留下了 118 个分析过的类和 829 个 Javadoc 注释，我们为它们手动生成了真实的可执行规范。我们的实验比较了三种工具，所有这些工具均由程序员编写的非正式英语规范来创建可执行过程规范。
l @tComment [50]与三种不同类型的无效性规范的预定模板匹配。我们希望使用@tComment 实现，但是由于文档数量有限而无法使用（例如，其文件格式未记录）。我们发现，更容易根据发布的描述重新实现@tComment [50] 。我们实现的@tComment 取得了与本文相似的结果，并公开供外部检查。
l Toradocu [24]通过 NLP 和字符串匹配的组合，从@throws 注释中生成特殊的后置条件。我们使用了来自 GitHub 的 Toradocu 实现。
l Jdoctor 是本文描述的工具。我们没有在比较中考虑 ALICS [42]，因为即使在作者的支持下，我们也无法使该工具正常运行（有关此问题的更多信息，请参见第 8 节）。而且，ALICS 没有产生可执行的规范，因此很难进行比较。
5.2 准确度结果 (RQ1, RQ2)表 2 报告了@ tComment、Toradocu 和 Jdoctor 在表 1 的主语类上的准确性。如第 2 节所述，Toradocu 不处理先决条件，Toradocu 和@tComment 都不处理正常的后置条件（表中的值 n.a. ）。表格中的数据表明，Jdoctor 的精度可与最新方法相媲美，而 Jdoctor 的召回率远高于最新方法。

文章插图

? 前置条件。Jdoctor 处理不同类型的前置条件，而@tComment 仅处理通过简单分析处理的与 null 相关的检查。@tCom 的精度比 Jdoctor 更高，这得益于其模式的特殊性，例如“may be null”，“must not be null”和“ @throws IllegalArgu.mentException if...is null” 。但是，对@tComment 的简单分析会错过许多翻译，导致召回率比 Jdoctor 低得多。
? 正常的后置条件。Jdoctor 是唯一足以表达@return注释的方法。由于常见返回条件的复杂性，@return注释的精度和召回率均低于其他标记。例如，注释“ @return 排序了的数组”声明后置条件为检查例程返回的数组是否已排序。该检查涉及对阵列的循环，在 Jdoctor 的当前实现中不支持此检查。其他难以检查的条件是，例如 Commons Math 中的FastMath类中的注释“ @return n + 1，如果没有发生溢出”，其警卫应检查是否发生了溢出。精度和召回率相对较低的另一个原因是后置条件通常包括两个或多个元素之间的比较。目前，Jdoctor 假定主题和谓词转换为单个 Java 元素，并且无法处理更复杂的情况，例如“如果a和c的大小差不等于 1”，“如果最大迭代次数小于或等于最小迭代次数”和“如果xval和yval大小不同” 。