• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Tim Cooke
  • paul wheaton
  • Paul Clapham
  • Ron McLeod
Sheriffs:
  • Jeanne Boyarsky
  • Liutauras Vilda
Saloon Keepers:
  • Tim Holloway
  • Carey Brown
  • Roland Mueller
  • Piet Souris
Bartenders:

Javadock for getters/setters

 
Ranch Hand
Posts: 48
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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?
 
Ranch Hand
Posts: 3389
Mac MySQL Database Tomcat Server
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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.
 
Bartender
Posts: 2292
3
Eclipse IDE Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Ranch Hand
Posts: 48
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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
Posts: 2292
3
Eclipse IDE Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Posts: 48
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Yes I think I will provde javadoc for all my public members aswell. Just to be sure
Thanks for the input
 
Ranch Hand
Posts: 57
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
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
Bartender
Posts: 2292
3
Eclipse IDE Spring Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

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.
 
reply
    Bookmark Topic Watch Topic
  • New Topic