I have a three-tier Spring web application and I need to improve its javadoc for classes, members, methods, etc.
Since the service tier and DAO tier are interface-based design, I have interfaces and implementation classes for both tiers. The implementation classes are largely the replica of the interface. The DAO tier interfaces are similar to their corresponding interfaces in the service tier.
Should I javadoc each method and its arguments in the interface and then do the same thing for its implementation class? This would be repetitive, boring, and inefficient.
Should I only javadoc interfaces? Javadoc implementation classes only on as-needed basis? I would like to know how other folks handle this matter.
You should write JavaDoc only for interfaces. Nobody writes them for implemented methods
Joined: Oct 12, 2003
stanislav bashkirtsev wrote:You should write JavaDoc only for interfaces. Nobody writes them for implemented methods
Thanks for your input!
As I indicated, the DAO interfaces are very similar to their corresonding interfaces in the service tier. Do you also javadoc DAO interfaces the same way as you do for service tier?
Joined: Aug 17, 2009
Of course. Today you use your dao with your services, tomorrow someone will try to use your dao with his own mechanism. Think about future. This rule is valid not only for Java
Joined: Oct 12, 2003
stanislav bashkirtsev wrote:Of course. Today you use your dao with your services, tomorrow someone will try to use your dao with his own mechanism. Think about future. This rule is valid not only for Java
It's because comments from base class differ from the comments of derived classes. If you don't want to change comment of derived class, you wouldn't write them. If you are looking at JavaDoc of some class and you want to see methods of base one, you just go to the methods of that class. How many times have you seen equals is commented in any of classes(except Object and AbstractList)?
Btw, when we talk about the code - doubling is a bad thing. We can apply this principle to the comments too
The whole purpose of javadoc is to expose, "WHAT" a method or a class or a type is doing, and not "HOW"; In case of interfaces, you write the whole java doc, the implementation will simply be:
(This is default behavior for Eclipse IDE as well); Simply because interface javadoc tells you what can be expected consistently from implementations, as a client using that code, I DO NOT care "HOW" it is being done; oh and if implementation is different , then this is breaking of the contract ... NOT GOOD!
To Original Poster,
Javadoc everything, except for fields (On my open source frameworks, some of our developers javadoc even the fields (I just think it clutters up additional space)).
This is my personal opinion (and what I think is the best practices), people write stuff all the time that is devoid of any documentation (not good IMHO)... and think that its the best, so whatever works for you guys! =)
Joined: Jul 05, 2005
Another good example of benefit of writing JavaDoc for implementations is Integer#compareTo, String#compareTo.
"What" in superclasses, and subclasses can be different, they have the same consistency description of course but "What" in subclasses can be more specific.
"How" can be important in some cases especially when the operation is generic.