File APIs for Java Developers
Manipulate DOC, XLS, PPT, PDF and many others from your application.
http://aspose.com/file-tools
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Javadoc of private/protected methods/variables Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Soft Skills this week in the Jobs Discussion forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Javadoc of private/protected methods/variables" Watch "Javadoc of private/protected methods/variables" New topic
Author

Javadoc of private/protected methods/variables

James Clarke
Ranch Hand

Joined: Oct 04, 2004
Posts: 148
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 public.

Thanks,
J.C
Alex Belisle Turcot
Ranch Hand

Joined: Apr 26, 2005
Posts: 516
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 public.

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
Ranch Hand

Joined: Nov 25, 2007
Posts: 39
how about default?
Alex Belisle Turcot
Ranch Hand

Joined: Apr 26, 2005
Posts: 516
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
Ranch Hand

Joined: Sep 04, 2005
Posts: 169
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
Ranch Hand

Joined: Apr 26, 2005
Posts: 516
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
Ranch Hand

Joined: Oct 23, 2006
Posts: 93
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 ]

Vyas, Anirudh
Roberto Perillo
Bartender

Joined: Dec 28, 2007
Posts: 2268
    
    3

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.


Cheers, Bob "John Lennon" Perillo
SCJP, SCWCD, SCJD, SCBCD - Daileon: A Tool for Enabling Domain Annotations
Anirudh Vyas
Ranch Hand

Joined: Oct 23, 2006
Posts: 93
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
Bartender

Joined: Dec 28, 2007
Posts: 2268
    
    3

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
Greenhorn

Joined: Jun 23, 2009
Posts: 3
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 ...


http://flexingcode.blogspot.com/
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Javadoc of private/protected methods/variables