It's not a secret anymore!*
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Help, How much documentation is appropriate?? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Android Security Essentials Live Lessons this week in the Android forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Help, How much documentation is appropriate??" Watch "Help, How much documentation is appropriate??" New topic
Author

Help, How much documentation is appropriate??

christy smile
Ranch Hand

Joined: Oct 15, 2001
Posts: 101
Hi, Ranchers,
I would like to get your opinions about documentations in the code. How much documentation should be in the code? The coding convention in my company is that we should put documentation for every single member variable and instance method and class method. Is this appropriate for the Developer exam? I am thinking about generating the javadoc for the code, then, I realized that javadoc does not include anything that is private in the class, so do I really want to add documentation for the private member variables?
Thank you!
Christy
John Dale
Ranch Hand

Joined: Feb 22, 2001
Posts: 399
I don't know how much documentation you need, but javadoc does have an option to show all classes and members, even private.
Trevor Dunn
Ranch Hand

Joined: Jun 13, 2001
Posts: 84
I am not really sure what is appropiate. I can just tell you what I did. I commented for all methods and variables and produced javadoc just for the public and protected methods and variables.
The only time I did not provide comments was when the class inherited from an Interface that provided the comments. The javadoc utility automatically referes to the parent for the javadoc if a method or variable is overridden and a javadoc comment is not supplied

Trevor
Gennady Shapiro
Ranch Hand

Joined: Sep 25, 2001
Posts: 196
Christy,
please read the spec more carefully.
The FBN spec says to generate javadoc "for public members" , meaning you dont have to expose protected and privite members to javadoc but you should commnet them.
christy smile
Ranch Hand

Joined: Oct 15, 2001
Posts: 101
Thank you, y'all!
Christy
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: Help, How much documentation is appropriate??
 
Similar Threads
Java doc question...
java doc for private members
Javadoc documentation??
Using jcip annotation
NX: Sun "Must" and JavaDoc