- Check parameters for validity
- Make defensive copies when needed
- Design method signatures carefully
- Use overloading judiciously
- Return zero-length arrays, not nulls
- Write doc comments for all exposed API elements
This chapter is from the book
This chapter is from the book
This chapter is from the book
Item 28: Write doc comments for all exposed API elements
If an API is to be usable, it must be documented. Traditionally API documentation was generated manually, and keeping documentation in sync with code was a big chore. The Java programming environment eases this task with a utility called doc comments. The Javadoc utility provides an easy and effective way to document your APIs, and its use is widespread.
If you are not already familiar with the doc comment conventions, you should learn them. While these conventions are not part of the Java programming language, they constitute a de facto API that every programmer should know. The conventions are defined The Javadoc Tool Home Page [Javadoc-b].
To document your API properly, you must precede every exported class, interface, constructor, method, and field declaration with a doc comment, subject to one exception discussed at the end of this item. In the absence of a doc comment, the best that Javadoc can do is to reproduce the declaration as the sole documentation for the affected API element. It is frustrating and error-prone to use an API with missing documentation comments. To write maintainable code, you should also write doc comments for unexported fields.
The doc comment for a method should describe succinctly the contract between the method and its client. With the exception of methods in classes designed for inheritance (Item 15), the contract should say what the method does rather than how it does its job. The doc comment should enumerate all of the method's @param tags.
In addition to preconditions and postconditions, methods should document any .
To describe its contract fully, the doc comment for a method should have a ). By convention the text following a @param tag or @return tag should be a noun phrase describing the value represented by the parameter or return value. The text following a @throws tag should consist of the word “if,” followed by a noun phrase describing the conditions under which the exception is thrown. Occasionally, arithmetic expressions are used in place of noun phrases. All of these conventions are illustrated in the following short doc comment, which comes from the List interface:
/** * Returns the element at the specified position in this list. * * @param index index of element to return; must be * nonnegative and less than the size of this list. * @return the element at the specified position in this list. * @throws IndexOutOfBoundsException if the index is out of range * (<tt>index < 0 || index >= this.size()</tt>). */ Object get(int index)
Notice the use of HTML metacharacters and tags in this doc comment. The Javadoc utility translates doc comments into HTML, and arbitrary HTML elements contained in doc comments end up in the resulting HTML document. Occasionally programmers go so far as to embed HTML tables in their doc comments, although this is uncommon. The most commonly used tags are <p> to separate paragraphs; <code> and <tt>, which are used for code fragments; and <pre>, which is used for longer code fragments.
The <code> and <tt> tags are largely equivalent. The <code> tag is more commonly used and, according to the HTML 4.01 specification, is generally preferable because <tt> is a font style element. (The use of font style elements is discouraged in favor of style sheets [HTML401].) That said, some programmers prefer <tt> because it is shorter and less intrusive.
Don't forget that escape sequences are required to generate HTML metacharacters, such as the less than sign (<), the greater than sign (>), and the ampersand (&). To generate a less than sign, use the escape sequence “<”. To generate a greater than sign, use the escape sequence “>”. To generate an ampersand, use the escape sequence “&”. The use of escape sequences is demonstrated in the @throws tag of the above doc comment.
Finally, notice the use of word “this” in the doc comment. By convention, the word “this” always refers to the object on which the method is invoked when it is used in the doc comment for an instance method.
The first sentence of each doc comment becomes the summary description of the element to which the comment pertains. The summary description must stand on its own to describe the functionality of the entity it summarizes. To avoid confusion, no two members or constructors in a class or interface should have the same summary description. Pay particular attention to overloadings, for which it is often natural to use the same first sentence in a prose description.
Be careful not to include a period within the first sentence of a doc comment. If you do, it will prematurely terminate the summary description. For example, a documentation comment that began with “A college degree, such as B.S., M.S., or Ph.D.” would result in a summary description of “A college degree, such as B.” The best way avoid this problem is to avoid the use of abbreviations and decimal fractions in summary descriptions. It is, however, possible to include a period in a summary description by replacing the period with its numeric encoding, “.”. While this works, it doesn't make for pretty source code:
/**
* A college degree, such as B.S., M.S. or
* Ph.D.
*/
public class Degree { ... }
It is somewhat misleading to say that the summary description is the first sentence in a doc comment. Convention dictates that it should seldom be a complete sentence. For methods and constructors, the summary description should be a verb phrase describing the action performed by the method. For example,
ArrayList(int initialCapacity)— Constructs an empty list with the specified initial capacity.
Collection.size()— Returns the number of elements in this collection.
For fields, the summary description should be a noun phrase describing the thing represented by an instance of the class or interface or by the field itself. For example,
TimerTask— A task that can be scheduled for one-time or repeated execution by a Timer.
Math.PI— The double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter.
The doc comment conventions described in this item are sufficient to get by, but there are many others. There are several style guides for writing doc comments [Javadoc-a, Vermeulen00]. Also, there are utilities to check adherence to these rules.
method does not have a doc comment, Javadoc searches for the most specific applicable doc comment, giving preference to interfaces over superclasses. The details of the search algorithm can be found in The Javadoc Manual.
This means that classes can now reuse the doc comments from interfaces they implement, rather than copying these comments. This facility has the potential to reduce or eliminate the burden of maintaining multiple sets of nearly identical doc comments, but it does have a limitation. Doc-comment inheritance is all-or-nothing: the inheriting method cannot modify the inherited doc comment in any way. It is not uncommon for a method to specialize the contract inherited from an interface, in which case the method really does need its own doc comment.
A simple way to reduce the likelihood of errors in documentation comments is to run the HTML files generated by Javadoc through an HTML validity checker. This will detect many incorrect uses of HTML tags, as well as HTML metacharacters that should have been escaped. Several HTML validity checkers are available for download, such as weblint [Weblint].
One caveat should be added concerning documentation comments. While it is necessary to provide documentation comments for all documentation comments with an external document describing the overall architecture of the API. If such a document exists, the relevant class or package documentation comments should include a link to it.
To summarize, documentation comments are the best, most effective way to document your API. Their use should be considered mandatory for all exported API elements. Adopt a consistent style adhering to standard conventions. Remember that arbitrary HTML is permissible within documentation comments and that HTML metacharacters must be escaped.