Re: best practices for *application* javadoc
Harold Shand wrote:
Eric Sosman wrote:
I'll second Joshua's advice, and mention an additional benefit:
The act of documenting what a method does clarifies your thinking on
what it should do and helps avoid the "Oh, gee, I never thought of
that" effect. If you can state the method's purpose in a few clear
sentences, you've got a better chance of writing its Java well. (And
if the description drags on and on and on, you've got a good hint that
the method is too intricate and should probably be decomposed.)
This is all true and good. But there's documentation and then there's
Javadoc. The code already has traditional /**/ comments explaining the
tricky parts and I definitely propose to use Javadoc for the unusual
methods anyway (and I did say both these things in the original post).
My question is wrt how helpful it is to Javadoc the basic building
blocks (getters, setters, toString methods, etc). For example, given the
presence of a traditional comment explaining what an 'index' does, is
there a point to writing full Javadoc for a getIndex method? A consumer
of an API wouldn't have access to the internal commenting, and so would
be dependent on the Javadoc, but a developer has no such problem.
But I guess the most compelling counterargument would be that an
incomplete API document is almost more confusing than none, so Javadoc
should either be complete or not present at all. That may be the right
answer.
There's a matter of degree, yes. If you're writing a method
that implements something in an interface, I think it's fine to rely
on the interface's own Javadoc; parroting it adds little value (maybe
even negative value). Similarly if you're overriding a method that's
well-described in its superclass, unless the subclass' specialization
puts things in a new light. I seldom write Javadoc for hashCode() or
equals() -- but I *do* often write it for toString(), if only to say
whether the format is or is not fixed in stone.
Tricky parts -- Back when I was young and dumb I used to delight
in writing tricky code, believing myself clever for doing so. Now I
realize that I was just being young and dumb ... I now try to avoid
writing things that are tricky, and when I can't avoid it I put in
a comment to explain it. Usually these comments tell why I know
that some condition holds without needing to be tested, or why a
construct looks funny. Here's one from actual code:
den = BigInteger.ONE.shiftRight(exp); // left, really: exp < 0
But in any event the tricky bits almost never belong in the Javadoc
anyhow: they describe the "how" of a particular implementation that
you might scrap and re-write tomorrow, rather than the "what" that
is the immutable contract the rest of the program relies on.
The incomplete Javadoc is, as you say, potentially confusing.
Somebody modifying the code -- as Joshua suggests, this might be you
yourself in six months' time -- may read it, spot an oddity, and
wonder whether it's an intentional special case or just a bug. If
there's a clear statement of the "what" available, it'll be a big
help in resolving the question.
--
Eric.Sosman@sun.com