Javadoc of private/protected methods/variables

[James Clarke]

Hi all,

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 coderanch.

Thanks,
J.C

[Alex Belisle Turcot]

Originally posted by James Clarke:
Hi all,

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 coderanch.

Thanks,
J.C

That is correct, I did not javadoc private/protected members & methods. You can but you don't have to.

Alex

[fei lin]

how about default?

[Alex Belisle Turcot]

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.

Alex
[ April 03, 2008: Message edited by: Alex Belisle Turcot ]

[mohamed sulibi]

hi all;

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
internal code.

Best Regards.
Mohamed Darim.

[Alex Belisle Turcot]

Originally posted by mohamed sulibi:
hi all;

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
internal code.

Best Regards.
Mohamed Darim.

Hi,

of course it's great to document everything. However, it is definitly not mandatory for the project.

Alex

[Anirudh Vyas]

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.

Whats your take on this ?


Regards
Vyas, Anirudh
[ April 05, 2008: Message edited by: Anirudh Vyas ]

[Roberto Perillo]

Howdy, y'all.

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.

[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 ?



Regards
Vyas, Anirudh

[Roberto Perillo]

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 ]

[Michael Matthee]

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 ...