Win a copy of Design for the Mind this week in the Design forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Help, How much documentation is appropriate??

 
christy smile
Ranch Hand
Posts: 101
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 399
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 84
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 196
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 101
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thank you, y'all!
Christy
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic