Win a copy of Programmer's Guide to Java SE 8 Oracle Certified Associate (OCA) this week in the OCAJP forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

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

 
david zhang
Greenhorn
Posts: 27
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 75
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
You should write JavaDoc only for interfaces. Nobody writes them for implemented methods
 
david zhang
Greenhorn
Posts: 27
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 75
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 27
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 12617
IntelliJ IDE Ruby
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Consider using the @see Javadoc "annotation".
 
david zhang
Greenhorn
Posts: 27
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
David Newton wrote:Consider using the @see Javadoc "annotation".


David, that is a good idea! Thanks!
 
Hong Anderson
Ranch Hand
Posts: 1936
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
stanislav bashkirtsev
Ranch Hand
Posts: 75
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1936
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 100
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 1936
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic