aspose file tools*
The moose likes Spring and the fly likes Best practices for writing javadoc for a Spring-style web application? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Soft Skills this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Frameworks » Spring
Bookmark "Best practices for writing javadoc for a Spring-style web application?" Watch "Best practices for writing javadoc for a Spring-style web application?" New topic
Author

Best practices for writing javadoc for a Spring-style web application?

david zhang
Greenhorn

Joined: Oct 12, 2003
Posts: 27
Hello,

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.

Thanks!
stanislav bashkirtsev
Ranch Hand

Joined: Aug 17, 2009
Posts: 75
You should write JavaDoc only for interfaces. Nobody writes them for implemented methods
david zhang
Greenhorn

Joined: Oct 12, 2003
Posts: 27
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?

Cheers!
stanislav bashkirtsev
Ranch Hand

Joined: Aug 17, 2009
Posts: 75
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
david zhang
Greenhorn

Joined: Oct 12, 2003
Posts: 27
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


I really appreciate your input!

Thanks again!
David Newton
Author
Rancher

Joined: Sep 29, 2008
Posts: 12617

Consider using the @see Javadoc "annotation".
david zhang
Greenhorn

Joined: Oct 12, 2003
Posts: 27
David Newton wrote:Consider using the @see Javadoc "annotation".


David, that is a good idea! Thanks!
Hong Anderson
Ranch Hand

Joined: Jul 05, 2005
Posts: 1936
stanislav bashkirtsev wrote:Nobody writes them for implemented methods

Hm, where do you get that conclusion? It's useful to write JavaDoc for implementation.
You can see an example from java.util.AbstractList JavaDoc.


SCJA 1.0, SCJP 1.4, SCWCD 1.4, SCBCD 1.3, SCJP 5.0, SCEA 5, SCBCD 5; OCUP - Fundamental, Intermediate and Advanced; IBM Certified Solution Designer - OOAD, vUML 2; SpringSource Certified Spring Professional
stanislav bashkirtsev
Ranch Hand

Joined: Aug 17, 2009
Posts: 75
Kegkaj Sathianpantrarit wrote:You can see an example from java.util.AbstractList JavaDoc
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
Hong Anderson
Ranch Hand

Joined: Jul 05, 2005
Posts: 1936
stanislav bashkirtsev wrote:
Kegkaj Sathianpantrarit wrote:You can see an example from java.util.AbstractList JavaDoc
It's because comments from base class differ from the comments of derived classes.

Yes, that's why we should write JavaDoc for implementation in that case. But if there is no different, no JavaDoc is needed.
Trilochan Bharadwaj
Ranch Hand

Joined: Feb 02, 2009
Posts: 100
Keng,

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! =)

Trilochan.
Hong Anderson
Ranch Hand

Joined: Jul 05, 2005
Posts: 1936
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.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Best practices for writing javadoc for a Spring-style web application?