Java annotations for design patterns?

Answer 1

nice interesting ideas. I have so far not heard about annotating design patterns. What happens if a class participates in more than a pattern ?

Answer 2

This seems like a misuse of annotations to me. Sure, I could see why you might want to note what design pattern a class is helping to implement, but just using the Javadoc and/or the name of the class seems more appropriate. The name of the pattern that you're using is of no actual importance to the code itself... patterns are just a guide for an often used way of solving a problem. A comment would suffice, rather than creating a new file for every pattern you use.

Answer 3

This is an interesting solution, but I keep wondering what's really the problem you're solving with this? Or in other words, what do you get from using something like this what you don't get by a proper comment on top of your class about it's usage?

I can think of a few cons but can't think of benefits apart from this being the nice standardized way to document code.

Cons would be, namely:

1. one more thing for programmers to think about, which is never a good thing
2. unannotated patterns might be confusing - someone probably forgot to document it, but maybe it's not a pattern..?
3. can you really annotate all patterns..? what about patterns which are not tied to a single class/method, for example three-tier architectural pattern, or thread pool, or even MVC?

Answer 4

If you can also write an annotation processor that will verify certain properties of the pattern - for example checking for common mistakes when implementing the pattern - this would be very useful. Documentation for the compiler as well as the programmer.

Answer 5

Firstly, what you want to do is documenting an intention (or intention*s*).

So, why not use a generic version of your annotation, something like @UsePattern that use @Documented which is a marker annotation (nice tuorial from IBM)? What i don't like is that the annotation is kept at runtime, which is a waste unless you want to affect program semantics.

Or a Custom Javadoc tag which seems more appropriate.

Some information about the comparison: Comparing Annotations and Javadoc Tags with a nice one sentence summmary:

<< In general, if the markup is intended to affect or produce documentation, it should probably be a javadoc tag; otherwise, it should be an annotation. >>

There is/was also some debate on documentation as annotation or as javadoc tags.

Answer 6

I just stumbled on another article that is interesting for you:

http://onjava.com/lpt/a/3340

Which talks about marker interfaces, like Serilizable.

In their words:

...just because a class declares that it "implements Serializable" doesn't mean that it has correctly implemented the Serializable contract.

Since Java can't really tell if the contract has been met, using the marker interface is more of an explicit pledge by the programmer that it has.

The overlooked benefit of marker interfaces is that they also document the intention that a contract should be met...

 

Why haven't design choices traditionally been recorded in source code? Mostly, because there has been no clear place to put them.

Even if each "typesafe enumeration" class had a comment noting that it followed that pattern, any elaboration (much less tutorial information) would not have been added because one either had to copy it repeatedly, or worse, place it sporadically in arbitrary spots.

When creating the JavaDoc comments attached to each Design Marker interface, one can put in more detail than is typical because the comments do not need to be repeated anywhere else.

They also mention some downsides, this a good food for thought!

Answer 7

Else there is this 2008 Computer Science paper: Design Pattern Implementation in Java and AspectJ, it was presented at OOPSLA 2008, which should give an indication about its quality.

A nice quote from it:

... the mere existence of classes that exclusively contain pattern code serve as records of what patterns are being used. In the AspectJ cases, we observe two additional improvements. First, all code related to a particular pattern instance is contained in a single module (which defines participants, assigns roles, etc.). This means that the entire description of a pattern instance is localized and does not “get lost” [21] or “degenerate” [7] in the system. Secondly, with the current AspectJ IDE support, all references, advised methods etc. are hyperlinks that allow a developer an overview of the assignment of roles and where the conceptual operations of interest are...

Answer 8

What would be better would be to use annotations to actually build the boilerplate for a Builder. Let's face it most are pretty standard.

@Builder("buildMethodName")
Class Thing {
  String thingName;
  String thingDescr;
}

Typical useage:

Thing thing =
      new Thing.Builder().setThingName("X").setThingDescr("x").buildMethodName();

Answer 9

Seems like a misuse of annotations to me. Unless there is the intention of implementing behavior with those annotations, I'd use the KISS principle: Plain ol' javadoc does fine for documenting what the artifact is supposed to do/be; custom doclets for extending javadoc; and google for those who want to know what a X or Y pattern is for (or a link to it somewhere on the web.)

There are excellent, quasi-official explanations for most patterns out there. Why writing your own? Is there additional information that is crucial for the project? Using annotations to make sure one can navigate from one class' javadoc to a custom-written pattern javadoc is like the tale of the CEO who assembled a development team for creating a report that combines the totals of two existing quarterly reports - it was too difficult (and yet cheaper) to add the totals of the two with a calculator 4 times a year :-/

Answer 10

First off all this is a very good idea and I'm only hanging out here because I googled for a "design pattern annotation" library. Good I found this! I will check it out and give feed back on it soon.

To all the skeptics: sorry obviously most of you are not very experienced in the topic of design patters. E.g. Martin Harris's post from Dec 3 '09 at 21:56 ... I understand you wanted to keep your "example" simple. But that is not a Builder in the sense of the Design Pattern.

The same I want to say to those who don't see the usefulness at all. If the relations of classes regarding to their roles in design patters are annotated to the class, I can use a generator to craft the boilerplate code. I see all relations on top of the class in the source code and can use my IDE shortcuts to navigate to the relevant classes.

If you have learned to think in patterns and all patterns are obvious in the source code (via comments or annotations) you can grasp a system composed of 200 classes in less than an hour.

Regarding suggestions like using @UsePattern() or @Builder("buildMethodName") etc. ... here we have to ask, how to make it "typesave"? After all those strings are prone to typos.

One advantage of proper annotations is that you can annotate roles ... Most Design Patterns do not consist out of a single class (like Singleton) but out of several classes working together! E.g. if you have a builder the result (annotated with @Product) might be also a @Composite. So the parts the builder is putting together will be @Component (in regard to the @Composite) and a @Part (in regard to the @Builder and the @Product).

Perhaps the best argument to such annotations would be java.lang.class, so you can express that.

Anyway, just a few thoughts ... I cant await to get home and play with the stuff you have so far ^^

BTW: a nice tool/plugin for code generation is found here http://spoon.gforge.inria.fr/

Answer 11

Michael Hunger and I have started an open-source project for annotations to specify what patterns the classes belong to. We are right at the beginning stages, but would love to hear your input.

I would like to go with the KISS principle in order to make it as easy as possible for people to use the annotations. For example, if you are writing an adapter, you can simply say:

@AdapterPattern
public class EnumerationIteratorAdapter<T> implements Enumeration<T> {
  ...
}

Of course, you can specify more information if you want, for example the role, the participants and a comment. We hope that this will make it easy for developers to mark-up their classes clearly.

The project home is on http://www.jpatterns.org from where you can also access the initial source tree. Please contact me on heinz at javaspecialists dot eu if you would like to contribute to the project.

Heinz (The Java Specialists' Newsletter)