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
"traditional"?
Javadoc comments are a convenient and conventionally structured way to
document your code. What possible reason could you possibly have to even
think about not including them? Laziness?
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.
Javadoc comments do no harm and are very useful. The burden of proof is on
the argument to omit them, not the one to include them.
Surely you see the value of commenting each method in your code. If not, then
the rest of the syllogism collapses, and shame on you.
Javadoc comments are useful in that the have a well-understood layout -
one-line description, @param list, @returns, @throws and Bob's your uncle.
They take all the heat out of thinking about how to structure your code
comments. They are well supported by tools like Eclipse and NetBeans. They
cover in their most automatically-generated forms the basics you need to
document anyway, and the effort to fine-tune them is far less than the effort
to comment your code raw without a conventional structure that is
well-supported by tools.
So stop being such a bloody lazy whiner and comment all your code with Javadoc
comments. Private, public, protected, package-private - with the exceptions
that Eric Sosman mentioned. (My version of that is to not Javadoc
@Override-notated common methods, such as the ones he mentioned: equals(),
compareTo(), ... Also, Javadoc @see obviates others.) Otherwise,
Javadoc-comment the hell out of your code.
There is no benefit whatsoever to skimping in this regard. Go overboard. Put
in too many Javadoc comments.
As for "traditional" comments, ptui. I spit on them. Your code should be
clear enough that comments are minimal, and only there to provide guidance
where they are truly needed. Most people put pointless garbage in internal
comments that would have been much better served just by writing clearer code.
Stick to Javadoc comments.
Remember, this diatribe is just about the comments. The questions of what
Javadocs to publish is entirely separate.
--
Lew