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

JavaDoc for constructors?

 
Roy Mallard
Ranch Hand
Posts: 53
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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?
 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Rudolph Jen
Ranch Hand
Posts: 37
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 37
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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
Posts: 214
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.

 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic