Java Reference
In-Depth Information
are meant to be fit together, and how the package might be extended for more functionality
(and why it wasn't extended in that way originally). For a programmer coming into the pack-
age for the first time, it shows the overall structure and gives the newcomer a foothold on the
various pieces.
One thing to notice about the
package-info.java
file is that links need to use the fully qualified
class or interface name. This is because of an interesting catch-22 of such files. Document
comments are only processed before a declaration. The only declaration that can appear in a
package-info.java
file is the declaration of the package. So the document comments need to
appear before the declaration of the package so that the tool generating the documentation will
read it. But prior to the package declaration, there is no reference package for the links. So you
need to put in the fully qualified name of the class or interface. This is something of a hassle,
but is worth it to get some general description of the interaction of those package pieces into
the documentation.
Style Guides, Editors, and Nonterminating Discussions
Over the years, there have been lots of discussions of what
proper
document comments should
look like. Various groups have issued style guides. Perhaps the best known of these guides is
“How to Write Doc Comments for the Javadoc Tool” (
http://java.sun.com/j2se/javadoc/writ-
ingdoccomments
)
, which goes into mind-numbing detail on how these comments should be
written. It covers everything from which person to use (third) to the length of the lines of your
comments (80, showing that the influence of punch cards will never die).
Now, I have no general objections to standards, either for documentation comments or for
source code. Every organization should have some style guide, to ensure that practices that
can lead to errors are avoided and help give uniformity to the work that comes out of the or-
ganization. More importantly, it helps those who have to maintain the documentation (and the
code) when they need to plunge into what you have written and make changes in the future.
But like coding conventions, documentation conventions should be considered as guidelines,
not as inflexible rules. Finding a set of guides that work for your organization is a good ex-
ercise, but doing so will almost certainly mean that some members of the staff will want to
control things that seem way too minor to worry about. A sense of proportion is needed in
such discussions, but rarely found. My experience has been that discussions of documentation
conventions soon become similar to discussions about coding conventions or which editor is
superior. They don't end.
