Java, as a mainstream programming language evolves to always trying to fit the latest needs. One big leap has been introduced in Java 5, with several language changes. One of them was the possibility to do some meta-programming. Big word isn’t it? Indeed, meta-programming.
In Object Oriented Language like Java, you will usually construct your software using object (cars, tires, engines …) and methods (move, turn, explode …) to describe your business into something computer will understand. Sound simple right?, in theory, this is pretty simple. Things become difficult when we need to save data, display things to a screen, connect to the network. Software engineer has invented APIs (Application Programming Interface) to help application developer to interact with 3rdParty libraries in general and display, network or system libraries in particular.
This is when our code start to be un-maintainable because we mix business code (cars, tires, engines) with technical plumbing (readfile, display, connect).
Java 5 has introduced annotations, a mechanism allowing to give information to our object without being part of it. Meta-programming. One simple example is the old “deprecated” keyword.
In java, you can say that a method will soon disappear, and to say that, you just need to “annotate” your method.
Today, many frameworks are “annotations” based, meaning you can describe your software behavior without even writting a line of code, just writting some annotations to your business code to make the “plumbing”.
After a while working with annotations, you will find it can become even more messy than an old spagetty plate. So, where are the limit, where should I use annotations, where should I not?
My opinion is, annotations are good for describing your code, but as soon as your annotation “does” something (@Inject, @In, @DoesSomethingWithoutTellingWhat 
), you should avoid them.
To give you some examples, Hibernate in java allow to annotate your model (tires, cars, engines, …) and say what IS your model and describe it. Hibernate will pickup from this meta-information and save your data into a database. At the opposite, you will find Jboss Seam where everything is made of annotations, you can actually “do” plenty of stuff using annotation, this is where i found annotations useless. It doesn’t help code readability nor performance. It’s just a lazy approach to do stuff you don’t understand.
Obviously people will like them because they can produce something working in 5 minutes. But what after these fives minutes, it will took more times to understand what the annotations are currently doing than reading simple line of codes.
One of the biggest mental leaps I made when I first started using Annotations was from “this is cool!” to “but should I use it…”
I agree completely. The purpose of your code, including annotations, is to describe the problem and a solution to it.
The breaking point, for me, was when I was using XStream annotations. After annotating all my classes in such a way that my XML output looked perfect, I realized I needed the same classes to have an alternate XML output. Then I realized what I had done – allowed view logic to write itself all over my domain objects. I’m very careful about annotation use now.
[...] This post was mentioned on Twitter by Alban Seurat. Alban Seurat said: RT @DZone "Annotation or not | Alkpone.com" http://dzone.com/auzp [...]
Travis, you could have written your own annotation processor and do the same thing that XStream does or introduce your own annotations for alternative xml output.
Travis, even cooler idea would be to re-use xstream annotations and if the field has to look different than mark it with your custom annotation.
Another guideline I find useful is to consider whether the annotation is referencing an external entity. I believe that the code becomes less maintainable if references to external entities are buried within annotations.
For instance, I like using JPA annotations (either with pure JPA or Hibernate), but I avoid using any of the annotations that specify actual Database entities, like table names or column names. These go into the mapping file, not in annotations.
Annotations are clearly an improvement in allowing a developer to specify things that are close to the code but I agree with the sentiment about excessive annotations causing clutter.
Annotations for things like OXM (object XML mapping) or ORM (object relational mapping) are inappropriate in my opinion for the reason Travis highlighted. You want to reuse your domain objects and these types of annotated mappings limit the reuse in certain circumstances.
JPA for instance allows one to override the mapping annotations while JAXB does not.
That said, it can be a fairly subjective argument.
[...] Annotation or Not, the post’s author enters the debate regarding when it is appropriate to use and not to use [...]
A very subjective argument, which depends a lot on what practices you (and your team, if you are on one) prefers to follow.
My team attempts to steer in a more domain-driven direction, and having “view” logic such as OXM in a “model” class in the middle of my domain breaks the single-responsibility principle. Now my domain objects do their job, as well as “display” themselves.
You could, for example, do like raveman suggested and make the Annotations more “magic”. But should you? Alternatively, XStream allows programatic description of the XML mappings. I could, instead, create a class whose job it is to know how a particular domain aggregate maps to XML. Then, if I wanted a second mapping, all I have to do is create a second class. Assuming I’m using dependency injection, I now just have to ensure the right XML Generator is being injected to the right places, and my system doesn’t have to worry about it.
I find this pattern far easier to understand and maintain, and in my experience newcomers to a project seem to have an easier time too.
Hi, I represent http://www.everygreenthing.net, we have a green business and blog directory and your blog is perfect for our site, please check us out, add your great green blog to the directory, its free and other people can read your awesome blog. Thanks for keeping the Earth greener!