Why javadoc parameter-less constructors?

Question

In item 56 of Effective Java (Third Edition), Joshua Bloch states: "Public classes should not use default constructors because there is no way to provide doc comments for them."

The default contructor doesn't do anything unexpected, though, it just makes a new instance. What sort of information ought to be documented in a doc comment on the parameter-less constructor that shouldn't just live in the class comment?

I can understand doing this if a class has interesting behaviour in initializer blocks (since otherwise there is no where to doc comment these), or even non-standard value assignments for fields (perhaps calling methods to get initial values). But it seems like for most classes this doesn't add much. Is there something I'm missing?

item 56 in EJ-3rd edition is another topic: https://i.imgur.com/OjKxK4s.png — ΦXocę 웃 Пepeúpa ツ, Mar 19 '18 at 20:30
To clarify, is the question related to javadocs for default constructors, or is it about the javadoc comments for non-default but no-parameter constructors? — Tin Wizard, Mar 19 '18 at 21:10
That line is in item 56 in the 3rd edition. That topic is the correct one. — Tom Tresansky, Mar 19 '18 at 21:18
The question is about the necessity of adding explicit no-argument constructors just to doc them. — Tom Tresansky, Mar 19 '18 at 21:20

davidxxx · Answer 1 · 2018-03-19T21:30:53.227

5

In the very most of cases you are right.
And I think that in these cases, using the default constructor makes sense as you has nothing to document.

Now in some other cases, it makes be useful to document what the method does and more specifically its default state.

Because even if a default constructor has an empty body, it may use a default value in its fields that may be interesting to document.

Here are two examples of JDK classes where javadoc may bring useful information for constructors with an empty body.

Stack

/**
 * Creates an empty Stack.
 */
public Stack() {
}

Of course, clients may guess that the Stack is empty as this constructor is invoked but having its clearly specified is better.

AtomicInteger

Take the AtomicInteger empty constructor:

/**
 * Creates a new AtomicInteger with initial value {@code 0}.
 */
public AtomicInteger() {
}

The AtomicInteger constructor is overloaded. So we are not in a potential default constructor case.
But whatever, it is an empty-arg constructor with an empty body, similar to what a default constructor produces.

Without these constructors javadoc, clients of these classes should look into the implementation to guess the information and an API that constraints clients to look the implementation to understand its specification is not a good designed API.

edited Mar 19 '18 at 21:30

answered Mar 19 '18 at 20:32

davidxxx

125,838
23
214
215

You are right about that, except that this is just parameter-less constructor, not a default one. In the case of default constructor, you can't have any other constructor, so all you need to document can be a part of class documentation. – v6ak Mar 19 '18 at 20:53
@v6ak Indeed. This is the first example found in my head from the JDK. I will try to find a "real" default one :) – davidxxx Mar 19 '18 at 20:59
`Stack` has an explicit sole constructor which acts like a default constructor with the Javadoc `Creates an empty Stack.` – d.j.brown Mar 19 '18 at 21:25
@d.j.brown You are better than Google you :) – davidxxx Mar 19 '18 at 21:31
@d.j.brown I see there are such cases, but I believe that reasons for putting information to such parameterless constructors with no alternatives are rather academical. There's nothing wrong with that, but we could live without that. – v6ak Mar 19 '18 at 22:55
I agree and in most cases it seems redundant. I guess the point Bloch is trying to make is that all aspects of the exposed API should be documented, and default constructors prevent this from being the case. – d.j.brown Mar 19 '18 at 23:04

Why javadoc parameter-less constructors?

1 Answers1