This week's book giveaways are in the Java EE and JavaScript forums.
We're giving away four copies each of The Java EE 7 Tutorial Volume 1 or Volume 2(winners choice) and jQuery UI in Action and have the authors on-line!
See this thread and this one for details.
The moose likes Developer Certification (SCJD/OCMJD) and the fly likes Javadoc for all or public classes? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of The Java EE 7 Tutorial Volume 1 or Volume 2 this week in the Java EE forum
or jQuery UI in Action in the JavaScript forum!
JavaRanch » Java Forums » Certification » Developer Certification (SCJD/OCMJD)
Bookmark "Javadoc for all or public classes?" Watch "Javadoc for all or public classes?" New topic
Author

Javadoc for all or public classes?

Brian Kelly
Ranch Hand

Joined: Jan 04, 2007
Posts: 54
"...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??


SCJA, SCJP (1.4), SCJD
Mark Smyth
Ranch Hand

Joined: Feb 04, 2004
Posts: 288
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.


SCJP<br />SCJD
Brian Kelly
Ranch Hand

Joined: Jan 04, 2007
Posts: 54
Thanks. Sounds sensible!
Zhixiong Pan
Ranch Hand

Joined: Jan 25, 2006
Posts: 239
Do I need to add comments in front of the class definition to explain why that class is created?


SCJP 1.4 SCJD
Zhixiong Pan
Ranch Hand

Joined: Jan 25, 2006
Posts: 239
BTW, most of my class variables are private. Should I leave them uncommented?
Mark Smyth
Ranch Hand

Joined: Feb 04, 2004
Posts: 288
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

Joined: Jan 25, 2006
Posts: 239
Mark, I agree with you. And how about comments for a class to explain the motivation of creating that class.
Tim Anlauf
Greenhorn

Joined: Oct 11, 2006
Posts: 22
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

Joined: Jan 25, 2006
Posts: 239
I don't think so. The comments given by Sun can be enough.
 
With a little knowledge, a cast iron skillet is non-stick and lasts a lifetime.
 
subject: Javadoc for all or public classes?