Java By Comparison

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 ...