Simple Guide to basic Javadoc
Javadoc tool is in my opinion one of the most underestimated tools available for a Java developer. Recently I have started digging into some opensource projects when looking for a nice examples of design patterns and I was surprised at high quality of their code in terms of commenting. This is something I, and many people I know, forget to do while producing source code every day.
Following the principle to leave the source in a better condition every time we open it in the IDE, I will leave here a simple example of a nice and clean class comment:
(example from JHotDraw)
* Tool to select and manipulate figures.
*
* A selection tool is in one of three states: 1) area
* selection, 2) figure dragging, 3) handle manipulation. The different
* states are handled by different tracker objects: the
* <code>DefaultSelectAreaTracker</code>, the <code>DefaultDragTracker</code> and the
* <code>DefaultHandleTracker</code>.
*
* A Figure can be selected by clicking at it. Holding the alt key or the
* ctrl key down, selects the Figure behind it.
*
<hr />
* <strong>Design Patterns</strong>
*
*
<em>Strategy</em>
* The different behavior states of the selection tool are implemented by
* trackers.
* Context: {@link SelectionTool}; State: {@link DragTracker},
* {@link HandleTracker}, {@link SelectAreaTracker}.
*
*
<em>Chain of responsibility</em>
* Mouse and keyboard events of the user occur on the drawing view, and are
* preprocessed by the {@code DragTracker} of a {@code SelectionTool}. In
* turn {@code DragTracker} invokes "track" methods on a {@code Handle} which in
* turn changes an aspect of a figure.
* Client: {@link SelectionTool}; Handler: {@link DragTracker}, {@link Handle}.
*
<hr />
*
* @author Werner Randelshofer
* @version $Id: SelectionTool.java 718 2010-11-21 17:49:53Z rawcoder $
*/
public class SelectionTool extends AbstractTool{
.................... class source code ..........
}
Some comments on the comment itself:
1. Use
style for keywords and names.
Keywords and names are offset by
when mentioned in a description. This includes:
* Java keywords
* package names
* class names
* method names
* interface names
* field names
* argument names
* code examples
2. add links for API names (listed immediately above) using the
tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length in source code doc comments).
3. User @Code instead of if you have to include some special chars in it eg.
see the Joseph D. Darcy's Oracle Weblog for more info.
4. Use the @author tag and don't be ashamed of your code :)
See more example of good commenting in JHotDraw project
One response on “Simple Guide to basic Javadoc”