Is there a Java annotation for bugs?

Question

I'm looking for a standard Java annotation that allows me mark some code as "related to bug PROJECT-312". The goal is to be able to create a report where I can see which parts of the code were changed or impacted by a bug. This would, for example, allow to see "hot spots" where a lot of bugs accumulate. Or it would make it easy to go from the IDE to JIRA/BugZilla to see what the bug is all about.

Is there a standard annotation that I can/should use or do I have to write my own?

PS: I'm aware of Mylyn/Tasktop which would do the tracking for me. For my purposes, these tools are too disruptive right now since they substantially change how people have to work every day.

Answer 1

Oracle approach

The Java API Specification should contain assertions sufficient to enable Software Quality Assurance to write complete Java Compatibility Kit (JCK) tests.

This means that the doc comments must satisfy the needs of the conformance testing by SQA. The comments should not document bugs or how an implementation that is currently out of spec happens to work.

From the official JavaDoc guidelines:

Code bugs are bugs in the implementation rather than in the API specification. Code bugs and their workarounds are often likewise distributed separately in a bug report. However, if the Javadoc tool is being used to generate documentation for a particular implementation, it would be quite useful to include this information in the doc comments, suitably separated as a note or by a custom tag (say @bug).

So basically it's telling you don't mix documentation with bug reporting. Use and parse a special custom tag in comments, you don't really need more than that for a successful bug report.

Also, with Eclipse Jira Connect or similar tools you can have your @bug and TODO comments transformed to bug/task tickets automatically.

Update

If you must, you could do with a couple of custom annotations. Tailor to your needs, document and enforce across the team. More on it here.

@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.

Answer 2

I'm not personally convinced annotations are the right way to track hot spots. For one, they'll get ugly in areas with lots of bugs (more @Bug lines than real code!) and for another, they'll unhelpfully populate places that aren't likely to regress, like an Off-By-One error when some code is first implemented.

More to the point, an @Bug annotation is only useful if it's used, and used consistently. Enforcing this will be a hassle for all involved, and will slow people down without actually providing much insight, since you have no way of knowing what code was impacted by a bug and didn't get annotated.

Better, I would say, would be to implement some external analysis that looks at the files impacted by bug fix revisions (Commit message contains [bB][uU][gG]:? *\d+ or something similar) and runs analysis that way. You can rapidly inspect all bug fixes, without adding any extra process for your developers.

Google has an interesting paper to this end: Bug Prediction at Google

---

To your comment about annotations being more "sticky" than comments, that they have a better chance of survival, I would similarly wonder how often that difference would be valuable in practice. I find it more often that bug comments in code are no longer informative, and stick around longer than they should as is. If svn|hg|git|whatever blameing the relevant lines doesn't reveal the commits associated with the bug in question, it's likely been iterated on several times since then, yet the comment sticks around.

I'm certainly not saying what you describe never happens, but I wonder how often this is really the case. If in your experience comments disappear when the could have still been helpful, by all means, see if annotations might do better.