adam bien's blog

Marker Annotation - for marking concepts, ideas and patterns 📎

During yesterday's smoke test, I checked in the Marker Annotation "Pattern" to p4j5. I borrowed the name from the "Marker Interface" Pattern.
However, I use Marker Annotations to annotate project-wide concepts and ideas in a lean and convenient way. Instead of writing JavaDoc (which is not typesafe - you can mispell the tags), I use lean annotations to mark patterns/idioms/concepts, and JavaDoc for the remaining (parameters, returnvalues etc.) tasks.
Defining an annotation isn't really hard. For e.g. the following snippets is used to mark the "Service" pattern from p4j5:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@Documented
public @interface Service {
/**
*
* @return The main responsibility of the documented concept.
 */
  String essentialResponsibility();
   /**
    *
    * @return The difference between the concept from MAD and the realization
    */
   String delta() default "";
}

All such annotations has to be defined outside the project and deployed as a jar. Then they can be easily used:

@Service(
 essentialResponsibility="CRUD"
)
public class SeviceBean implemens Service {

}

Some benefits:
  1. Less documentation to write (actually a huge one).
  2. The meta-information is accessible in bytecode and can be processed with e.g. apt.
  3. The architecture can be validated afterwards (e.g. searching for unallowed dependencies between patterns) - the tools are able to access the annotations.
The meaning of the annotation can be kept in the annotation itself and e.g. in wiki. Especially information like:
  • Transactionality
  • Concurrency
  • Remoting (@Local, @Remote)
can be stored in one place. Redundant documentation is nasty to write and maintain...