I have worked in a lot of places before my current assignment, usually the policy is that you dont java doc the private methods, this is because you dont want people to be reading documentation for the API that isn't meant to be shared with everyone.
However, my current assignment place has a few people who are stickler for java doc-ing private methods which apparently i dont agree with.
I'm adding JavaDoc to all my methods, but just generating them for public and protected methods. This way I cover whoever has to maintain the code in the future and those who'll just use application's API.
Originally posted by Anirudh Vyas: but then whats the use of adding java docs to the private methods ... in that case simple comments would suffice imho, isn't it ?
In my opinion, adding JavaDocs to all methods (including private methods) make the code much more readable. There, you can show the purpose of the method, how it works, info about each parameter, a more complete info about the return of this method, and when each exception can happen. JavaDocs were made to comment methods. Simple comments were made to comment code. So, I think adding them to all methods make the code more complete. [ April 05, 2008: Message edited by: Roberto Perillo ]
According to the code conventions from Sun Microsystems, we have two different types of comment.
(A) The first is an implementation comment which looks like this:
* Comment here !
(B) The other is a documentation comment that looks like this:
* Comment here !
All the private methods that need documenting are implementation dependent, so that would mean comments like (A).
All the public interface methods should go into your JavaDoc's, and those would be comments like (B).
However, in my opinion, one shouldn't be wasting time documenting all and every single private method.
If it's not going to add any value, and your private method is rather short,
the comments are just an added burden of maintenance.
If you want your code to be understandable, easy to maintain and re-factor,
then rather spend more time reading up on Uncle Bob's clean code book,
and less time refactoring your comments ...