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 constructors? 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 constructors?" Watch "JavaDoc for constructors?" New topic
Author

JavaDoc for constructors?

Roy Mallard
Ranch Hand

Joined: Jul 14, 2005
Posts: 53
Some of my classes have a zero-arg public constructor automatically generated.
Am I supposed to generate JavaDoc comments for these? The requirements state that I have to have javadoc comments for "each element of the public interface of each class". So is the automatically generated constructor part of the "public interface" or not?


SCJP 1.4<br />SCJD
Mihai Radulescu
Ranch Hand

Joined: Sep 18, 2003
Posts: 916

Roy

Every class must have an constructor, even if is very tempting don't relay on the automatically generated code.
A first advantage is that you can document the constructor .

regards M


SCJP, SCJD, SCWCD, OCPJBCD
Rudolph Jen
Ranch Hand

Joined: Nov 17, 2006
Posts: 37
I would comment a constructor, if you use (for example) DependencyInjection to add some needed functional components. There it could be good to comment such constructors.
But I would not add any comment to default-constructors. Actually you only could write a comment without any overvalue.

Regards R


SCJP<br />SCJD (in progress)
Mihai Radulescu
Ranch Hand

Joined: Sep 18, 2003
Posts: 916

hi Rudolph,


... and javadoc style comments must be used for each element of the public interface of each class


Please remark the must.

Regards M.
[ January 15, 2007: Message edited by: Mihai Radulescu ]
Rudolph Jen
Ranch Hand

Joined: Nov 17, 2006
Posts: 37
Yep, but public interface is IMHO the methods that could be could called from outside (not the constructor). I know, that everybody tries to interpret every single word in the assignment. Perhaps Sun wants us to comment all constructors (even the no-arg ones), but I do not see any sense in that.

But I still don't know it of course.

But to be sure, I admit, to add some comments does not hurt. Only "do not provide comments that do not add to the comprehensibility of the code". I have to ask my Mentalo.

Regards R
Lewin Chan
Ranch Hand

Joined: Oct 10, 2001
Posts: 214
Well, if it's a requirement to javadoc all "each element of the public interface of each class", then you should do it .

Regardless, it might be useful anyway to state what the defaults are if the noparam constructor is called. After all, not everyone will have access to the source when they come to use your API.



I have no java certifications. This makes me a bad programmer. Ignore my post.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: JavaDoc for constructors?