Metadata - extending your code with annotations and javadoc
Published: 11:02 PM GMT+12, Sunday, 8 February 2004 under:
technology intellij-jira-plugin
Earlier in the day there was a discussion on #java/efnet about J2SDK 1.5's new annotations, and I happened to mention the @jira javadoc annotation and @jira() 1.5 annotation I was thinking of adding to my plugin, this sparked a few statements I'd like to comment on:
toad_: talios metabilities is dumb. so are jira-specific annotations!First - metabilities: its a silly term I came up to describe the capabilities extended to an application when you start feeding it metadata. So the term sucks a little, but if the world can survive with such terms as blogosphere, I can live with metability. As for jira-specific annotations - whats wrong with that? I'm working on a JIRA specific plugin for IDEA, so wheres the problem in provided JIRA specific annotations, especially when the annotation replates specifically to JIRA. Metadata can be generic, but can also be specific. I have a few ideas in the back of my mind about what things I could do once I've build up metadata about my source code, and how they relate to issues that may have sparked them. Hani also had something to contribute to this:
fate: yes, I was just about to say @jira is dumb fate: since there is no sensible correlation between a method/class and a jira issue. fate: it's not like you when you get a bug, you write a new method as the fix.You may not write a method AS the fix, but you may extract a method, push it up to a superclass, refactor a little, and then fix the bug using the extracted method. All I'm promoting here is the automatic annotation that these methods were touched, for the purpose of fixing a specific issue. When developer X comes along and looks at whats changed in the code, he gets to see why method X was introduced.
toad_: fate well if you look over java source, you will see refs to bug numbers, eg 'see bug #2234321' toad_: but i dont see why you would want tags that only work with jira fate: toad_: yes, that's fine, but that goes in source code, not method docs fate: toad_: it's a // type thing fate: when reading javadocs, who the hell cares about the bugs it fixed?The only reason I'm using JIRA specific tags, is that the integration works ONLY with JIRA, and that the integration is looking for things dealing with JIRA. It doesn't care about bugzilla, bugzero, or anything else, its for JIRA. I do happen to aggree with Hani here that "see bug #2223421" is generally more a // type comment, but in sake of being consistent, and standard, I'm simply adding the annotation once to the method, within the javadoc comment. This keeps the metadata cleanly away from the grunt of the code, but localized enough that its still relavent. You don't add // type comments to EVERY line either. And as for reading the javadocs? Well, unless you're customzing javadoc, @jira tags won't be rendered anyway, so you won't know about issues when reading the javadocs. The other side of having such metadata would allow me to customize JIRA to display a list of affected classes/methods for a particular issue, linking to a ViewCVS page of the affected code, which would be a very handy feature. I personally think that adding metadata is a good thing, and at the end of the day - you don't have to use it if you don't want to.
What about test classes and methods? You may not write a new method to fix the issue, but you would most certainly write a test class and/or test method to test the issue. I can see an @jira tag coming in handy in such a situation so you could list any and all jira issues the test method applies to.