File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Javadock for getters/setters 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 » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Javadock for getters/setters" Watch "Javadock for getters/setters" New topic
Author

Javadock for getters/setters

Jim Petersson
Ranch Hand

Joined: May 28, 2008
Posts: 48
Hi,
I know the spec says we are to provide javadoc for "for each element of the public interface of each class."
Does this mean we have to write javadoc comments even for simple get/set methods?

Let's say you have a method like:
public String getDatabaseName()

Feels a bit unnecessary to write a javadoc comment saying someting like:
"Returns the name of the database"

But maybe we have to?


SCJP 5<br />SCJD
Raghavan Muthu
Ranch Hand

Joined: Apr 20, 2006
Posts: 3355

I don't think so of the necessity of the javadoc for each field. Even in such case, you can easily generate by using some rules/templates i believe! I have never tried that.


Everything has got its own deadline including one's EGO!
[CodeBarn] [Java Concepts-easily] [Corey's articles] [SCJP-SUN] [Servlet Examples] [Java Beginners FAQ] [Sun-Java Tutorials] [Java Coding Guidelines]
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2268
    
    3

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.


Cheers, Bob "John Lennon" Perillo
SCJP, SCWCD, SCJD, SCBCD - Daileon: A Tool for Enabling Domain Annotations
Jim Petersson
Ranch Hand

Joined: May 28, 2008
Posts: 48
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.
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2268
    
    3

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.
Jim Petersson
Ranch Hand

Joined: May 28, 2008
Posts: 48
Yes I think I will provde javadoc for all my public members aswell. Just to be sure
Thanks for the input
Joshua Fix
Ranch Hand

Joined: Sep 18, 2007
Posts: 57
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


SCJP 5.0
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2268
    
    3

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.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Javadock for getters/setters