• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Tim Cooke
  • Jeanne Boyarsky
  • Paul Clapham
Sheriffs:
  • Devaka Cooray
  • Ron McLeod
  • paul wheaton
Saloon Keepers:
  • Tim Moores
  • Piet Souris
  • Tim Holloway
  • Stephan van Hulst
  • Carey Brown
Bartenders:
  • Al Hobbs
  • Frits Walraven
  • Scott Selikoff

Javadoc for all or public classes?

 
Ranch Hand
Posts: 54
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
"...and javadoc style comments must be used for each element of the public interface of each class."

"Provide javadoc documentation for all classes you write."

And under deliverables:
"A subdirectory called javadoc, containing HTML/Javadoc documentation for all classes and interfaces you are submitting. "

So which is it???

Javadoc for all or public?

I was going to do it for everything (private classes and methods) but it's driving me insane, so I want to check if it's necessary to write javadocs for everything??
 
Ranch Hand
Posts: 288
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Brian Kelly:
"...and javadoc style comments must be used for each element of the public interface of each class."

"Provide javadoc documentation for all classes you write."

And under deliverables:
"A subdirectory called javadoc, containing HTML/Javadoc documentation for all classes and interfaces you are submitting. "

So which is it???

Javadoc for all or public?

I was going to do it for everything (private classes and methods) but it's driving me insane, so I want to check if it's necessary to write javadocs for everything??



Javadoc all classes default, protected and public (class descriptions) and at least all public methods of each class. I provided javadoc for the protected members and methods as well. I dont think there is any need to javadoc private menbers and methods, as users of you class should not know this information anyway. Maybe regular comments for these would be fine.

Regards,
Mark.
 
Brian Kelly
Ranch Hand
Posts: 54
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Thanks. Sounds sensible!
 
Ranch Hand
Posts: 239
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Do I need to add comments in front of the class definition to explain why that class is created?
 
Zhixiong Pan
Ranch Hand
Posts: 239
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
BTW, most of my class variables are private. Should I leave them uncommented?
 
Mark Smyth
Ranch Hand
Posts: 288
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Zhixiong Pan:
BTW, most of my class variables are private. Should I leave them uncommented?



Zhixiong you should have javadoc comments explaining what the purpose of each class is. For private variables you shouls still comment them with at least a one line regular comment explaining what each is for.

Mark
 
Zhixiong Pan
Ranch Hand
Posts: 239
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Mark, I agree with you. And how about comments for a class to explain the motivation of creating that class.
 
Greenhorn
Posts: 22
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
What about implemenation of interfaces, do I have to add a comment to the public methods ?

For Example the the DBAccess interface defines the comments, do I have to add to an extra comment in Data class ?

Tim
 
Zhixiong Pan
Ranch Hand
Posts: 239
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I don't think so. The comments given by Sun can be enough.
 
reply
    Bookmark Topic Watch Topic
  • New Topic