• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Javadoc for public interface

 
Jared Cope
Ranch Hand
Posts: 243
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,

A must requirement for my assignment is javadoc for all the public API that I have written. I am not quite sure what to do in the case where I have classes without an explicit constructor though. When I javadoc these classes I get resulting HTML that has an un-documented empty parameter public constructor.

I can't decide if this violates the 'must' requirement or not. I really want to avoid including and documenting empty constructors in my code though just to avoid these situations in the resulting javadoc.

What do people think?

Cheers, Jared.
 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi, Jared

Every (non abstract)class must have at least one constructor, the generated default constructor is a safety belt - don't relay on this, don't relay on generated stuff(code) - base only on your code.

Regards M
 
Jared Cope
Ranch Hand
Posts: 243
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,

Originally posted by Mihai Radulescu:

Every (non abstract)class must have at least one constructor


When you say *must*, are you talking about your assignment spec or a compiler necessity or something else? I always thought it was perfectly fine to leave out an empty contructor, the compiler will insert one for you.

That said, the safest thing for me to do is to just add them in I guess. More of an annoyance than anything else.

Cheers, Jared.
 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I mean in general.
 
Jeroen T Wenting
Ranch Hand
Posts: 1847
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
empty constructors are best left out (as is everything that does nothing) though.
That's another (and stronger) best practice, a method without implementation (like a member or variable that's not used) reeks of an error (and is at the very least sloppy).
 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Jeroen,
This is a question of taste, I explain why with a small example :


if in the future I'll add a non-default constructor to the Super class I'll be surprised to get a compilation problem on Sub class.
Of course - the class designed for extension have no constructor, and this classes are not designed for extensions(then will be correct to declare them fina
l).
Other arguments
1.Java doc tool
2.Prevents a class from inadvertently being made instantiable

About empty methods, also "no silver bulit".

Regards M
 
Mihai Radulescu
Ranch Hand
Posts: 918
IntelliJ IDE Java Linux
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Jeroen,
This is a question of taste, I explain why with a small example :


if in the future I'll add a non-default constructor to the Super class I'll be surprised to get a compilation problem on Sub class.
Of course - the class designed for extension have no constructor, and this classes are not designed for extensions(then will be correct to declare them fina
l).
Other arguments
1.Java doc tool
2.Prevents a class from inadvertently being made instantiable

About empty methods, also "no silver bulit".

Regards M
 
Jeroen T Wenting
Ranch Hand
Posts: 1847
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
You may have a point, but IMO the empty constructor still reeks badly.

If you add a constructor later that breaks other code, you should then implement the no-arg constructor and will most likely find there's now some code to put there as well.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic