• 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
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

JavaDoc private fields and methods

 
Ranch Hand
Posts: 37
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
For the SCJD project, do you need to JavaDoc private fields and methods? It would seem using regular comments makes more sense, since these are private hence they are not to be exposed or known about to clients of the class. A javadoc is supposed to be an API reference so clients can use your code .. or am I getting this all wrong?
 
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
Howdy, Kenny!

For the SCJD project, do you need to JavaDoc private fields and methods?



Well champ, I do think it is a good idea to write JavaDoc comments even for the private members, in order to ease maintenance. You don't have to include them in the documentation, but if you want to include them one day, they are already there. You can include, for instance, protected and public members.

It would seem using regular comments makes more sense, since these are private hence they are not to be exposed or known about to clients of the class.



You mean the // comments? Well, I myself don't like them. If they are used, then it means that you are having to explain your code, which is something the code should do on its own. The code should be as clean as possible, which means that the methods shouldn't be big (up to 15 excluding '{' and '}' should be enough) and variables should have a proper name (i.e. "serverReference" instead of "sRef"), as well as the methods.

I myyself included JavaDoc comments for all class members.
 
Sheriff
Posts: 11604
178
Hibernate jQuery Eclipse IDE Spring MySQL Database AngularJS Tomcat Server Chrome Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Like Roberto I javadoc'ed every class member. I generated javadoc with the -package option (= shows only package, protected, and public classes and members), because I had a lot of package-private classes.

Although my code is clean and I use also proper variable names, I still use the // comment. For example, to add the jira-request number (when I have to add an extra line of code in an existing method), or to give a small explanation about the logic you followed (not only to help yourself remembering what you did several months later, but also to help your fellow developers understand what you did, without having to go through all lines of code to know what's going on),...
 
Don't get me started about those stupid light bulbs.
reply
    Bookmark Topic Watch Topic
  • New Topic