6

我正在寻找允许我将一些代码标记为“与错误相关PROJECT-312”的标准 Java 注释。目标是能够创建一个报告，我可以在其中看到代码的哪些部分被更改或受到错误的影响。例如，这将允许查看大量错误累积的“热点”。或者它可以很容易地从 IDE 转到 JIRA/BugZilla 以查看错误的全部内容。

是否有我可以/应该使用的标准注释，还是我必须自己编写？

PS：我知道Mylyn / Tasktop会为我进行跟踪。就我而言，这些工具现在的破坏性太大，因为它们极大地改变了人们每天的工作方式。

4

2 回答 2

3

甲骨文方法

Java API 规范应包含足以使软件质量保证编写完整的 Java 兼容性工具包 (JCK) 测试的断言。

这意味着文档注释必须满足 SQA 一致性测试的需要。注释不应记录错误或当前不符合规范的实现如何工作。

来自官方 JavaDoc 指南：

代码错误是实现中的错误，而不是 API 规范中的错误。代码错误及其解决方法通常同样单独分布在错误报告中。但是，如果 Javadoc 工具被用于为特定实现生成文档，那么将这些信息包含在文档注释中会非常有用，适当地将其分隔为注释或自定义标记（例如 @bug）。

所以基本上它告诉你不要将文档与错误报告混为一谈。在评论中使用和解析一个特殊的自定义标签，你真的不需要更多的东西来成功的错误报告。

此外，使用 Eclipse Jira Connect 或类似工具，您可以将您的评论@bug和TODO评论自动转换为错误/任务票证。

更新

如果必须，您可以使用几个自定义注释。根据您的需求量身定制，记录并在整个团队中执行。更多关于它的信息。

@Target({ ElementType.TYPE })
@Retention(RetentionPolicy.CLASS)
// Unavailable through reflection.
public @interface classbug {}
// gives you the @classbug annotation.

@Target({ ElementType.METHOD })
@Retention(RetentionPolicy.CLASS)// Unavailable through reflection.
public @interface methodbug {}
// gives you the @methodbug annotation.
于 2013-05-22T09:24:06.353 回答
2

我个人并不认为注释是跟踪热点的正确方法。一方面，它们会在有很多错误的区域变得丑陋（@Bug比实际代码更多的行！），另一方面，它们会无助地填充不太可能回归的地方，比如当一些错误时出现 Off-By-One 错误首先实现代码。

更重要的是，@Bug注释只有在被使用并一致使用时才有用。强制执行这对所有相关人员来说都是一件麻烦事，并且会减慢人们的速度，而实际上并没有提供太多洞察力，因为您无法知道哪些代码受到错误的影响并且没有得到注释。

我想说，更好的做法是实施一些外部分析，查看受错误修复修订（提交消息包含[bB][uU][gG]:? *\d+或类似内容）影响的文件并以这种方式运行分析。您可以快速检查所有错误修复，而无需为您的开发人员添加任何额外的流程。

为此，谷歌有一篇有趣的论文：谷歌的错误预测

对于您关于注释比注释更“粘”的评论，他们有更好的生存机会，我同样想知道这种差异在实践中多久是有价值的。我经常发现代码中的错误注释不再提供信息，并且比它们应该存在的时间更长。如果svn|hg|git|whatever blameing 相关行没有显示与相关错误相关的提交，那么从那时起它可能已经迭代了好几次，但评论仍然存在。

我当然不是说你所描述的永远不会发生，但我想知道这种情况多久发生一次。如果根据您的经验，评论在可能仍然有用的情况下消失了，请务必查看注释是否会做得更好。

于 2013-05-23T04:12:58.437 回答