• 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
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

JavaDoc for constructors?

 
Ranch Hand
Posts: 53
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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?
 
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Ranch Hand
Posts: 37
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
 
Ranch Hand
Posts: 214
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.

 
reply
    Bookmark Topic Watch Topic
  • New Topic