Originally posted by James Clarke:
I have not Javadoced any of the private methods or variables in my code.
Does anyone know if we are expected to Javadoc private/protected ? My understanding is that its normally only required for public.
That is correct, I did not javadoc private/protected members & methods. You can but you don't have to.
Originally posted by fei lin:
how about default?
Good question, never thought about it.. I never use the package modifier. I would say you don't have to.. only the public elements are a must.
The requirements for this is simply:
...javadoc style comments must be used for each element of the public interface of each class.
[ April 03, 2008: Message edited by: Alex Belisle Turcot ]
Originally posted by mohamed sulibi:
i don't think that don't put the javadoc for private .. is good idea, why
not ???, think about the person how will alter or modify or change your
of course it's great to document everything. However, it is definitly not mandatory for the project.
However, my current assignment place has a few people who are stickler for java doc-ing private methods which apparently i dont agree with.
Whats your take on this ?
[ April 05, 2008: Message edited by: Anirudh Vyas ]
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 ]
(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 ...