Java Reference
In-Depth Information
19.6. Notes on Usage
Tightly coupling the reference documentation to the source code has
many advantages, but it does not turn all programmers into good doc-
umentation writers. Programmers will continue to vary in their ability
and interest in writing good reference documentation. Many organiza-
tions have technical writers to produce the reference documentation. Doc
comments require write access to the source, and technical writers often
do not have permission to modify source code. The use of doc comments
will require a change in such organizations.
Another issue is
comment skew,
in which comments become out of date
as the source code changes over time. You can reduce this problem by
putting only contractual information in your doc comments and not de-
scribing the implementation. When the implementation changes, the doc
comment will still be correct as long as the contract remains unmodified.
Changing the contract of an existing type, constructor, method, or field is
a questionable practice in many cases, so such changes should be rare.
Describing only the contract is generally a good practice in any case be-
cause it frees you to change details of the implementation in the future.
Implementation details of methods need to be documenteduse regular
comments for this purpose.
You can further reduce the problem of comment skew by defining a
standard marker for programmers to place in doc comments that need
attention. For example, if you add a new method to a class, you could
write the first draft of the doccomment, but flag the comment as one that
might need review and rework by the documentation team:
/**
* ...initial draft...
* @docissue Review -- programmer's first draft
*/
A script run over the source could find
@docissue
markers and show them
to the documentation team, alerting them to work that remains to be
