Javadock for getters/setters

[Jim Petersson]

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?

[Raghavan Muthu]

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.

[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.

[Jim Petersson]

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]

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]

Yes I think I will provde javadoc for all my public members aswell. Just to be sure
Thanks for the input

[Joshua Fix]

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

[Roberto Perillo]

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.