为何要为无参构造器编写Javadoc？——基于《Effective Java》的疑问

Great question! Let's unpack this based on Joshua Bloch's guidance in Effective Java (3rd Edition) and common Java documentation best practices. The key distinction here is that class-level Javadocs focus on the overall purpose, design intent, and general usage of the class, while no-arg constructor docs should zero in on the specifics of creating an instance and its initial state/behavior—details that don't belong (or aren't precise enough) in class docs.

Here's what you should include in a no-arg constructor's Javadoc that shouldn't just live in the class Javadoc:

• Precise initial state of the instance
  Class docs might say something like "A resizable list implementation," but the no-arg constructor needs to spell out exactly what state you get when you call it. For example:

  Constructs an empty ArrayList with an initial capacity of 10.
  This is critical because users need to know if the instance starts empty, with default values, or pre-initialized with specific data—details that the class doc won't cover in this level of specificity.

• Hidden side effects or implicit initialization logic
  If the no-arg constructor does anything beyond simple object instantiation (like loading default configs, registering listeners, or connecting to a default database), this must be documented here. For example, if you have a ConfigManager class:

  Creates a ConfigManager instance that automatically loads the default.properties file from the classpath to populate initial configuration values.
  Class docs might only mention that the class manages app configs, but they won't call out this implicit behavior tied directly to instance creation.

• Differences from other constructors in the class
  If your class has multiple overloaded constructors, use the no-arg constructor's Javadoc to clarify how it differs from the others. For example, in a StringBuilder-like class:

  Constructs an empty character builder using the default UTF-8 charset. Use the StringBuilder(Charset) constructor to specify a custom character encoding.
  This helps users choose the right constructor for their use case, which class docs can't do for individual constructor variants.

• Special behavior from instance initialization blocks
  As you noted, if your class has instance initialization blocks (the code in curly braces outside of methods), these are inserted into every constructor by the compiler—including the no-arg one. Any non-trivial logic here (like generating a unique ID, setting default flags, or validating environment state) must be called out in the constructor's Javadoc. For example:

  Creates a new User instance. An instance initialization block automatically generates a globally unique UUID for the userId field during construction.
  Class docs won't typically detail the mechanics of how instance state is set up, so this belongs firmly in the constructor's documentation.

Bloch's point about avoiding default constructors makes perfect sense here: the compiler-generated default constructor gives you no way to communicate these critical details, leaving users guessing about what they're actually getting when they instantiate your class. By explicitly defining the no-arg constructor and documenting these specifics, you eliminate ambiguity and make your API much easier to use correctly.

内容的提问来源于stack exchange，提问作者Tom Tresansky