Structure JavaDoc of Classes and Interfaces
| | /** |
| » | * This class represents a cargo ship. |
| | * It can unload a {@link Stack} of supplies, load a {@link Queue} of |
| | * supplies, and it can show the remainingCapacity as a long. |
| | */ |
| | interface CargoShip { |
| | Stack<Supply> unload(); |
| | Queue<Supply> load(Queue<Supply> supplies); |
| | int getRemainingCapacity(); |
| | } |
Chances are you already know this, but you should document every public class or interface with JavaDoc. This is a rule in practically all Java projects.
The problem is that developers usually write JavaDoc last when their deadline is looming. If that happens, it might look like the comment above. And on the surface, it looks okay.
The JavaDoc comment contains both—a short summary and a more detailed description of the capabilities of the class. It even uses the @link annotation to connect to the data structure classes used.
But similar to the Structure JavaDoc of Packages, it’s lacking structure. The summary and the details are located right next to each other without vertical separation. This makes it harder to identify them as separate. But not only that, there are even errors in the comment.
The summary sentence simply repeats the name of the interface, and that doesn’t add much value. Even worse, it’s wrong, because CargoShip is an interface and not a class as the comment says.
The detailed description simply restates the method signatures of the interface. This can quickly get out of sync with the actual code: getRemainingCapacity() no longer returns a long value.
So how can we write a helpful comment that doesn’t just repeat the interface with its method signatures?
| | /** |
| » | * A cargo ship can load and unload supplies according to its capacity. |
| | * |
| » | * <p> |
| | * Supplies are loaded sequentially and can be unloaded in LIFO |
| | * (last-in-first-out) order. The cargo ship can only store supplies up to |
| | * its capacity. Its capacity is never negative. |
| | */ |
| | interface CargoShip { |
| | Stack<Supply> unload(); |
| | Queue<Supply> load(Queue<Supply> supplies); |
| | int getRemainingCapacity(); |
| | } |
Now the summary sentence is clearly standing out at the top of the JavaDoc comment. And it conveys helpful advice without just reiterating the name of the interface.
The following description provides more details about its behavior: using last-in-first-out, for instance.
What’s more, it states two conditions that the interface guarantees to the caller regarding its capacity. You might know such conditions from the JavaDoc comments of the java.util.List interface or other interfaces and classes with state. You call these conditions invariants because they never become false.
So here’s our recommendation for good JavaDoc comments for interfaces and public classes: First, start with a short and concise summary. Separate this vertically from invariants the class or interface guarantees. Don’t just duplicate method signatures.
And examples always help! So sit down and have a go at an example for how to use the interface above.