This week's book giveaways are in the Refactoring and Agile forums.
We're giving away four copies each of Re-engineering Legacy Software and Docker in Action and have the authors on-line!
See this thread and this one for details.
Win a copy of Re-engineering Legacy Software this week in the Refactoring forum
or Docker in Action in the Cloud/Virtualization forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

JavaDoc include private?

 
Matt Ghiold
Ranch Hand
Posts: 213
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hey guys,
Are you submitting your javadocs showing private members and methods or just public?
Thanks
 
Daniela Ch
Ranch Hand
Posts: 96
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
In my assignment they asked for the public interface only...
but dont be lazy and javadoc everything...
 
Peter den Haan
author
Ranch Hand
Posts: 3252
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I would suggest javadoccing everything, but not necessarily generating javadoc documentation for everything.
The first question you should be asking yourself is: who is the audience for these javadocs? My assumption was at the time that the primary audience for the javadocs are developers writing new code against your classes.
Generating Javadocs for public methods only is a bad idea. Why? Unless you make your classes final, developers can create subclasses of your classes and gain access to protected methods. So your minimum documentation level should be for public and protected methods.
Given the audience assumption above, generating Javadocs for all methods, including private ones, is also a bad idea. Why? Because external code can't get at private methods anyway. Documenting them introduces a lot of unnecessary information into the docs that only serves to clutter up and confuse. Private methods are only interesting for developers working on the class itself, and they already have the source code including the javadocs in front of them; if that's not enough for them, they should be capable enough to generate full docs themselves.
This leaves the decision whether to include package-private methods or not. This depends on whether you think your audience will be developing further classes in the same package(s) or not.
- Peter
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic