jQuery in Action, 3rd edition
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 Customer Requirements for Developers this week in the Jobs Discussion 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

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

Gennady Shapiro
Ranch Hand

Joined: Sep 25, 2001
Posts: 196
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!
It is sorta covered in the JavaRanch Style Guide.
subject: Help, How much documentation is appropriate??
It's not a secret anymore!