Structure JavaDoc of Constructors
| | class Inventory { |
| | |
| | List<Supply> supplies; |
| | |
| | /** |
| » | * Constructor for a new Inventory. |
| | */ |
| | Inventory() { |
| | this(new ArrayList<>()); |
| | } |
| | |
| | /** |
| » | * Another Constructor for a new Inventory. |
| | * |
| | * It is possible to add some supplies to the Inventory. |
| | */ |
| | Inventory(Collection<Supply> initialSupplies) { |
| | this.supplies = new ArrayList<>(initialSupplies); |
| | } |
| | } |
There’s one special type of method in Java that you can’t assign a good and meaningful name to: constructors. They always have the same name as the class. They may have a clearer purpose than other methods (they always construct an object), but if you misuse them, those objects will be flawed. That’s why you have to explain constructors with good and informative JavaDoc comments.
In the example above, the JavaDoc is poorly done. Neither of the summary sentences really carry new information, and they are rather obsolete. The second sentence in the lower constructor also misses the point. How are the supplies added exactly? Does the addition refer to the parameter initialSupplies or is there another method for that?
Also, there’s no hint on how the two constructors are related to each other. Normally when you use a third-party class, you don’t read the sources—only the JavaDoc. That’s why the JavaDoc comment of a constructor[28] must explain everything necessary for a programmer to use it.
So what do you have to know to use this class correctly?
| | class Inventory { |
| | |
| | List<Supply> supplies; |
| | |
| | /** |
| » | * Creates an empty inventory. |
| | * |
| | * @see Inventory#Inventory(Collection) instantiate with initial supplies |
| | */ |
| | Inventory() { |
| | this(new ArrayList<>()); |
| | } |
| | |
| | /** |
| » | * Creates an inventory with an initial shipment of supplies. |
| | * |
| | * @param initialSupplies Initial supplies. |
| | * Must not be null, can be empty. |
| | * @throws NullPointerException if initialSupplies is null |
| | * @see Inventory#Inventory() instantiate with no supplies |
| | */ |
| | Inventory(Collection<Supply> initialSupplies) { |
| | this.supplies = new ArrayList<>(initialSupplies); |
| | } |
| | } |
The first and most important thing you need to know is how to call a constructor correctly. You especially need to know what preconditions you have to fulfill so that everything works out as desired. The default constructor doesn’t really have preconditions and no input parameter, but the second one does: a Collection of Supply objects called initialSupplies. We have to document this one like we do with other method parameters. Here, you’re not allowed to enter null, and if you do, then you get a NullPointerException back. The comment states this in the @throws part.
Second, you need information about the state of the object when the constructor finishes, because its state determines which other methods you can call at this point. That’s called a postcondition. In the code above, the inventory’s either going to be in an “empty” state or filled with “initial supplies.” The summary sentences of both constructors describe that.
But there’s even more in the comments: two @see annotations. These annotations provide hints to the developer. They outline alternatives that she may not have seen otherwise. Here, we use these annotations to explain the relationship between the two constructors.
Because constructors lack a name, their JavaDoc is just so important!