Structure JavaDoc of Methods
| | interface CargoShip { |
| | |
| | Stack<Supply> unload(); |
| | |
| | /** |
| » | * Loads {@link Supply}. |
| | * |
| | * @param supplies the supplies of type {@link Queue} |
| | * @return not loaded supplies of type {@link Queue} |
| | */ |
| | Queue<Supply> load(Queue<Supply> supplies); |
| | |
| | int getRemainingCapacity(); |
| | } |
From classes and interfaces (Structure JavaDoc of Classes and Interfaces), we are now moving one level deeper to JavaDoc comments for methods.
Methods represent the behavior of objects. By calling methods, you trigger state changes and side effects. That’s why documenting methods with JavaDoc is more important than any other kind of JavaDoc comments. You can even see that in most modern IDEs. They guide the programmer when selecting a method to call with a quick extract from the method’s JavaDoc comment. They’ll usually also support a quick lookup function for JavaDoc.
Do you notice the summary sentence and the @link annotations used here? As so many times before, they don’t add much helpful information in the comment.
And what about the other two lines in the comment—the input parameter marked with @param and the return value marked with @return? Here the comment describes nothing new—it just repeats the method signature.
So is this comment enough? Do you know what happens when you pass null instead of a Queue instance? Can a runtime exception occur for certain inputs?
No. No. And no idea. We have no clue how the method will behave, even though there’s a JavaDoc comment. So if we use this method, we’re no longer certain how our code will behave. That would be especially problematic if you’re building an API.
Let’s see what we can do about it:
| | interface CargoShip { |
| | |
| | Stack<Supply> unload(); |
| | |
| | /** |
| » | * Loads supplies onto the cargo ship. |
| | * |
| | * <p> |
| | * Only lets you load as many supplies as there is remaining capacity. |
| | * |
| | * Example: |
| | * <pre> |
| | * int capacity = cargoShip.getRemainingCapacity(); // 1 |
| | * Queue<Supply> supplies = Arrays.asList(new Supply("Apple")); |
| | * Queue<Supply> spareSupplies = cargoShip.load(supplies); |
| | * spareSupplies.isEmpty(); // true; |
| | * cargoShip.getRemainingCapacity() == 0; // true |
| | * </pre> |
| | * |
| | * @param supplies to be loaded; must not be null |
| | * @return supplies that could not be loaded because of too little |
| | * capacity; is empty if everything has been loaded |
| | * @throws NullPointerException if supplies is null |
| | * @see CargoShip#getRemainingCapacity() check capacity |
| | * @see CargoShip#unload() unload the supplies |
| | */ |
| | Queue<Supply> load(Queue<Supply> supplies); |
| | |
| | int getRemainingCapacity(); |
| | } |
This is much better now. The JavaDoc comment reads like a contract. It states how the input and its internal state must be to guarantee a certain output and state change.
The contract covers a good case with a description and a code example. Note that the < characters must be escaped with < because <pre> is an XML environment.
Even invalid input, such as null, is specified in the @param description, along with the consequences of a violation: @throws a NullPointerException.
What’s more, the comment refers to other methods via the @see annotation. It describes how you can undo the effects of the method or observe state changes caused by calling the method.
Just keep this in mind: the contract metaphor doesn’t fully apply—you can’t usually sue someone if the implementation differs from its specification.