This week's book giveaway is in the OO, Patterns, UML and Refactoring forum. We're giving away four copies of Refactoring for Software Design Smells: Managing Technical Debt and have Girish Suryanarayana, Ganesh Samarthyam & Tushar Sharma on-line! See this thread for details.
Honestly, I think it is very necessary. For instance, let's say that you give me the jar file of a component you created; without the JavaDocs of all methods that I can call, I'd never know that there is a getDatabaseName() there.
Originally posted by Roberto Perillo: Honestly, I think it is very necessary. For instance, let's say that you give me the jar file of a component you created; without the JavaDocs of all methods that I can call, I'd never know that there is a getDatabaseName() there.
Well, even if you dont provide any "javadoc-block" you will still see the method signature in the generated JavaDoc. And since the method name can be pretty selfexplanatory, there is usually no need to comment such methods.
Well, I never tried that, actually... but even so, I provided JavaDoc comments for all methods, including the getHotelName() one you know, since the instructions say that "javadoc style comments must be used for each element of the public interface of each class", I thought it would be better.
Joined: May 28, 2008
Yes I think I will provde javadoc for all my public members aswell. Just to be sure Thanks for the input
I think it makes sense to javadoc all public methods, even if they seem obvious and there isn't much going on with the implementation. Some get methods may have very complex implementations and may need explaining as to what it's returning and how/why. Blank javadoc for a public method leaves it all up to the reader's imagination
I struggled with the javadoc section a lot because I'm REALLY lazy and I hate documentation (when I have to write it!). I finally ended up deciding to javadoc EVERYTHING, even private stuff, with the hopes that maybe it makes it easier for the grader and I get a faster turn-around time. It was a dreadful experience, but I'm glad I did it
I finally ended up deciding to javadoc EVERYTHING, even private stuff
Good call. I did exactly the same thing. And a tip for everybody: look at the Java source code (it is in a file called src.zip, in the installation directory of the JDK) to see how they documented it. For instance, looking at the java.net.URL class (done by James Gosling, the father of Java), we can see that even the private methods were documented. I think that the Java source code is the best source to inspire us on how to build the code.