InfoQ had an interesting article on annotations a few days ago - Annotation Hammer. In it, the author tries to show the good and bad points of annotations. It's an interesting article, but I don't quite think the article covers enough of the intricacies of annotation usage.
Annotations or XML?
Venkat gives a couple good examples of annotation usage, persistence and web services, and then shows security as an example of where annotations don't make sense. I'll provide some counterpoint here, because the examination is very shallow. Security is something that might actually be very wise to express in annotations.
I'll argue that security configuration very rarely changes at deployment. You obviously will create users and their permissions at/after deployment, but you aren't likely to be creating a new role. Roles are something that is intrinsic to the design of an application. Concepts like "admin" or "customer" or "manager" are not things you general add a couple lines to a deployment descriptor and make appear. Since these concepts are core to most applications and don't change, it's not a bad candidate for annotations the guide your security system.
Another important point is that annotations should not be your ONLY source of metadata about an object. A flexible framework that uses annotations should allow for external overrides. This is a critical point that most people who don't use annotations much miss. Take EJB3 for example. Everything that you annotate can also be expressed in XML. In this case, it makes sense to over-annotate the classes. If something changes at deployment, you can still express the changes in XML. However, things don't change much at deployment. Why go through the hassle of forcing XML configuration for the 95% of your configuration that never changes?
Convention Over Configuration?
The author then talks about convention over configuration. Although I like the concept of convention over configuration, I hate the term because I think the wording guides people astray. Venkat takes exception to the convention of prefixing a method name with test (testSomething(), for example) and using @Test as a marker for test methods. He says, why not just have the convention that all methods
are test methods? I think the annotation is superior to both of the conventions, but there is some room for debate.
I said I don't like the term "convention over configuration". I get a lot more mileage out of "configuration by exception" as a guiding policy. The idea is that things should have reasonable default behaviors and that you should only configure when you want something different. The catch is: what is a reasonable default behavior? Is it reasonable to assume that all methods are test methods?
Of course not. Test classes always have helper methods. There are probably more test methods than helper methods, so would it make sense to annotate the non-test methods? @NotATest doesn't seem like a very good alternative. The positive @Test makes perfect sense. It makes a positive, helpful statement to both the developer and the framework what the purpose of the method is. It does the same thing that the testMethod() convention does, but in a less intrusive way. The real kicker is that @Test annotation gives you a place to attach even more metadata to. If your testing system has test grouping, as one example, that's a perfect place to describe it.
The point that Venkat isn't entirely lost on me. He is arguing that although the class-level test annotation might make since the per-method annotations can get noisy. (Though I'd stress that your IDE should be able to do things like annotation hiding and folding to eliminate any perceived annotation clutter) The test example isn't a good example, because the conventions proposed are even worse, but there are cases where the argument holds. Transaction declarations are one place where Venkat's argument holds, and that example should be easy to understand for anyone developing web/enterprise applications.
Would you want to annotation @Transaction on every method? Probably not. You'd really like some reasonable default behavior. (Again, I avoid the term convention because what is a "convention" in this case? It's not a helpful way to examine the problem) With @Transaction, you'd look to the method to provide the transaction metadata. If there is no metadata, you'd look to the class level to see if there was a default set for the class. In an EJB3 application, you might also look for an EJB3 annotation that might imply a default transactional behavior. You could also then delegate to an application-wide configuration file to find the default. I find this works really well, and despite the warnings about annotation hell, it seems relatively easy to keep even hardcore annotation-wielding applications very clean.
The Advice
So, let's go through Venkat's final advice. I obviously agree with when he says you should use annotations, so what about the negative cases?
He says - don't blindly convert XML configuration to annotations. Obviously you don't do anything blindly, but I'd argue much of what you do in XML would likely be a good target for annotations. Just remember to leave yourself the capability override with external configuration.
He says - Metada is something you will want to change. I would argue metadata is something you THINK you want to change. It's something you want to have the option to change, even if you probably won't. With annotations you can leave yourself the option of XML without the burden of being forced to use it.
He says - to use conventions instead of configuration. This is generally good advice expressed in a way that often leads to poor decisions. I say that annotations are a great way to express your intentions. Don't be a slave to bad conventions - allow yourself the flexibility to configure the exceptional conditions.
Just to be clear, I don't recommend using annotations for everything in your application. There are many cases where annotations just don't make sense. However, I do think much of the advice you see is being overly conservative. Don't annotate just because it is new and cool, but don't be afraid to annotate either. I've been using annotations quite extensively for the last year, and over that time I'm regretted NOT annotating much more than I've regretted annotating.
Previous Topic
