江苏龙网

  1. 主页 > 生活百科 > >

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

代码注释


? 特殊的后置条件 。与@tComment 相比，Jdoctor 具有更好的精度和召回率 。@tComment 仅翻译与空相关的注释，即在特定上下文中包含单词“空”的注释 。例如，Jdoctor 可以翻译表达式“ aString 不为空”，而@tComment 则不能 。在分析复杂的句子时，Jdoctor 的句子分析比@tComment 的模式匹配更有效 。Jdoctor 可以翻译由许多从句与特定的语法连接相联系的从句组成的句子，例如x和y为正或z为负，而@tComment 的模式匹配则不然 。Jdoctor 比 Toradocu 具有更好的精度和召回率 。Jdoctor 的更好结果归功于更精确的算法，可以将主语和谓词转换为 Java 元素，并获得了更多受支持的注释集（请参见第 4 节） 。
? 92％的整体精度和 83％的召回率支持对 RQ1 的肯定回答：Jdoctor 在将 Javadoc 注释转换为过程规范方面有效且准确 。我们的评估还支持对 RQ2 的肯定回答：与最先进的技术@tComment 和 Toradocu 相比，Jdoctor 的准确率更高 。
5.3 不一致的规范通过检查每个 Javadoc 注释的 Jdoctor 输出，我们手动检查了第 5.2 节中报告的 Jdoctor 的准确性 。检查表明 Jdoctor 可以产生正确但不一致的规范 。尽管目前只能通过手动分析 Jdoctor 的输出来找到许多这些问题，但我们计划扩展该工具以自动报告它们 。现在，我们描述我们遇到的许多不一致之处 。我们发现，许多开发人员编写的规范在逻辑上是不一致的-也就是说，它们无法实现或不能被客户端使用 。这突出了将非正式的英语规范转换为可执行形式的附带好处：可执行形式中的不一致性比非正式表述并不明显，并且可以自动检查机器可读的规范 。下面我们报告 Jdoctor 可能突出显示的六类不一致和错误 。
? 一些规范会转换为并非总是定义良好的表达式，因为它们的求值可能会引发异常 。例如，当 arg 为 null 时 arg.f> 0，这可能导致两种合理但不同的解释：arg.f 表达式始终具有一个值（即 arg！= null && arg.f> 0）或条件只要 arg.f 具有值（即 arg！= null || arg.f> 0），则为 true 。两种解释都在实践中出现，尽管它们的含义对于客户和实施者而言都大相径庭 。
? 许多规范具有冲突的前提条件和后置条件 。Commons Collections 中的CollectionUtils类的一个简单示例是
l @param a第一个集合，不能为null
l @throws NullPointerException 如果a为null
@throws子句指的是违反@param子句的情况，导致两种规则上的解释，尽管相互矛盾：（i）方法的域是所有值（允许程序员传递null），并承诺当传入null时会发生什么，或（ii）该域都是非空值，程序员不应传递空值 。两种解释都是合理的，并且没有办法知道设计者的意图，但两者之间的区别是微不足道的：前者指出，维护者不得在将来更改实施，而后者则规定实施者可以在将来的实现中自由更改，依赖异常的客户代码将可能出错 。
? 一些规范指示给定条件的多个结果 。例如，让我们考虑
l @throws NullPointerException 如果arg1为null
l @throws IllegalArgumentException 如果arg2为负数
如果arg1为null且arg2为 0，则该例程需要同时抛出NullPointerException和IllegalArgumentException，这在 Java 中是不可能的 。没有注意到不一致的客户可能会遇到意外的行为 。这种不一致性的一个例子是JGraphT的KShortestPaths类 。后置条件中也会出现类似的不一致之处 。
? Jdoctor 自动识别 Javadoc 中的一些很可能是由于复制和粘贴错误引起的错误[6] 。例如，Guava 19.0 中CharMatcher.matchesNoneOf方法的文档指出：“如果此匹配器匹配序列中的每个字符（包括序列为空时），则返回 true”，同时应指出该方法不匹配序列中的任何字符 。Jdoctor 将拼写错误“匹配每个字符”正确转换为使用方法matchAllOf的 Java 表达式，并且此断言在运行时失败，突出显示了不正确的 Javadoc 。
? 某些过程的 Javadoc 引用了不正确的形式参数名称 。常见的原因是 Javadoc 从重写的实现中继承，并伴随着形式参数名称的更改 。HTML API 文档的读者会在 Javadoc 中看到一组名称，在方法名称中看到另一组名称 。通常，这种对应是显而易见的，但并非总是如此，读者不必推论它 。
? Jdoctor 还自动在 Javadoc 中报告了一些拼写错误 。例如，在 GraphStream 项目的Node类中，Javadoc 错误地说方法可能抛出IndexOutOfBoundException，而不是正确的IndexOutOfBoundsException 。Jdoctor 可能会报告问题，因为它没有在其类路径中找到类IndexOutOfBoundException 。


【将代码注释转换为过程规范】


推荐阅读


上一篇：这个diao 群消息已读回执，究竟是推还是拉？

下一篇：建议收藏 手摸手教你 CentOS 入门必备基础知识