Question : What do you get if you cross Java 5 annotations with Web 2.0?

Answer : Something like this - a tag cloud based upon annotations and their use within a codebase.

I didn't talk about annotations in my previous blog entry and the reason for this is that I'm not really a heavy user of them. A few @Override annotations here and there (courtesy of Eclipse), a couple of Spring @Transactional annotations and that's pretty much it. I've often thought about using annotations more (see Requirements coverage, for example) but the spark and necessity have never been there. However, now that I'm doing more Java 5 development and starting to use annotations, I've started thinking about other ways in which they could be used.

For me, the interest comes in trying to enrich a codebase with metadata that describes something more about the code than you can get from comments or the code itself. Or failing that, metadata that provides an easier way to find what you're looking for. For example, wouldn't it be great to see which code was considered to be "framework code"? What about making it easy to find those few really good examples of Oracle BLOB handling rather than saying, "they're somewhere in the DAO layer"? What about tagging up classes and methods with a keyword summarising their functional purpose. You've probably come across the Java Almanac during your travels - it's basically a whole bunch of useful code snippets that demonstrate how to use the various Java APIs. Now, imagine something like this across your own code. You probably have countless examples of APIs, techniques for doing things, implementations of patterns, gotchas and so on. Imagine attaching metadata to your source code by tagging it up, del.icio.us style.

@Keywords({"oracleblobhandling", "frameworkcode"})
@Keywords({"interestratecalculation", "businesslogic"})
@Pattern("factory")

Now, imagine for a moment that you've tagged up your source code and put effort into enriching the metadata associated with it. Something like the tag cloud shown above gives you an immediate view on which annotations you've used, how often they're used and so on. The screenshot above is a basic tag cloud that shows the annotations used within a codebase, the size of each showing the relative frequency with which each annotation is used. Click on an annotation and you can get more information about exactly where the annotation is used.

Just out of curiosity, I built a tag cloud from the Java 5 source code. Only 440 uses of @Deprecated. ;-)

Taking this concept further, you can get access to the actual values associated with annotation attributes, so it would be easy to build a tag cloud based upon only the values associated with an @Keywords annotation, for example. Effectively, you can filter and group on whatever level of annotation information you want to because it's all available via a set of APIs.

I've only just started playing with this so it'll be interesting to see how it pans out. Having attempted to generate tag clouds from a number of projects, I'll say the following. (1) Not many projects are using annotations (hence the small tag clouds!) and (2) the annotation processing APIs are a little verbose and sometimes unstable.

I'll save the technical details for another day, but essentially I've taken the tag cloud code out of Pebble and dropped it into an Annotation Processor, which gets executed through the Annotation Processing Tool (apt), via the apt Ant task that's included with Ant 1.7 beta 1.

What do you think? Would you find this a useful addition to your development environment?

Responses[4]

Posted by Simon Brown on 05 September 2006 21:29:00 BST #