5

I've looked across this forum, and I've googled this one, and I'm not sure what is the best way to handle Javadoc and annotations that appear together in the same class.

From what I can see from Sun/Oracle's documentation, they seem to suggest (though I cannot really find an explicit statement) that Javadoc should be listed atop annotations.

See their example How and When to Deprecate API's.

That works great for something simple like @Deprecated or @Override. But what about if you use JPA and/or Hibernate? Your classes and methods are bound to be annotated quite a bit more heavily (sometimes two or more annotations per class or method).

I'm guessing Javadoc still on top of annotations?

Also I wonder how should annotations best be used? I've seen some examples where the annotations "stack" on top of the class, member, method. And I've seen others where they list the annotations on the same line (usually a method here).

Which is best? Which is more readable?

And do you "document" that fact that you annotated something within your Javadoc or not?

I'm looking for either a good set of documentation about this and/or your own experience about what is most readable/maintainable.

Chris Aldrich
  • 1,904
  • 1
  • 22
  • 37
  • You don't need to explicitly mention that you added an annotation; annotations that have the `@Documented` annotation are automatically added to the documentation. – C. K. Young Aug 08 '11 at 14:12

2 Answers2

7

Javadoc is only place where you document class, method, etc. Annotations can change functionality of given code (like annotations from Hibernate or Spring). So, for me, it is obvious that annotations should be closer to code (so, between javadoc and method/function).

But how to write annotations, where there is lot of them? It depends, I prefer to leave them in separated lines, with few exceptions if there are short and connected in some way.

Explicit documenting in Javadoc that you are using annotations is not a good idea i think. Annotations can have @Documented annotations themselves, which states they should appear in generated javadocs. Beside this, it is implementation detail - javadoc should tell what method/object is made for, not how you are doing that (mostly, at least).

Adam Jurczyk
  • 2,153
  • 12
  • 16
0

I think you are mixing up code annotations and javadoc annotations.

javadoc comments are just that: comments. It doesn't matter for your application what actually is enclosed by /** */ (unless, of course you generate the javadoc)

Code annotations actually affect the functionality of your application. Your hibernate mapping classes won't work if you omit the annotations (and don't provide a hibernate configuration file). A method marked as @Deprecated only in the javadoc comment but not in the code won't be recognized as deprecated by the compiler. (the javadoc tool will possibly warn you in that case)

So yes, there are annotations in code and javadoc which share the same name, but they are totally different. In case of @Deprecated you should use both: to mark them deprecated in the code, and to document why.

pmnt
  • 379
  • 1
  • 6
  • no I'm not mixing them. I'm asking what is the best way to format them "in the code" to make the code readable. Technically you could list the annotations first, then javadoc, and then the source...although why I'm not sure. I'm asking more about from a code readability standpoint. – Chris Aldrich Aug 08 '11 at 14:19
  • ok ... Personally, I think annotations belong to the code: javadoc - annotations - source – pmnt Aug 08 '11 at 14:30