Re: best practices for *application* javadoc
Joshua Cranmer wrote:
Harold Shand wrote:
I have a web app with somewhat iffy documentation and a plan to
correct that. But in reading up on Javadoc it seems all the tutorials
and tips are aimed at developers of APIs. I fully appreciate the
importance of documenting APIs well, but in the case of a fully-bound,
end-user application those rules seem - at first glance anyway - to
be overkill. For instance, most methods are used in just a few places
and if I change a parameter to one the IDE (Eclipse in this case) will
immediately point out the places that need fixing. These methods will
never be used outside the app or overridden (they're final anyway) so
in the case of an application like this, laborious documentation of
method parameters feels like wasted time.
There's the "six month effect." If you stopped all work for six months
on the application, and then came back to it, would you remember
everything?
Even doing this three months later with little-documented code can
surprise you at how hard it is to read.
My recommendation, therefore, is to document it. And the more thorough,
the better. Your future self will thank you.
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.)
Personally, I write Javadoc even for private methods. True, I tend
to omit the careful HTML markup -- but I write the doc anyhow, and have
never found it to be a waste of time.
--
Eric.Sosman@sun.com