Re: best practices for *application* javadoc
Arved Sandstrom wrote:
My opinion, as regards the "internal" code: yes, it should have Javadoc. The
style would be no different - it is imparting the same information. 90%+ of
the classes inside a typical app serve as a library for the front end, and
should be designed and documented as if you were going to make that source
available as a library to the masses. An API is still being exported, it's
just that fewer people see it. It may in fact never be seen except by you
(the author), some reviewers, maybe a deployer, and some hapless
maintainers, but all of you need that documentation down the road.
Arved has the right of it.
From several perspectives, and the unanimity of responses in agreement
supports this, including Javadoc comments with just about everything is a
classic nobrainer. The example of one's own efforts to decipher one's own
intent after a time away is a canonical argument in their favor, offered by
just about everyone in favor of thorough documentation ever since source code
first allowed embedded comments. I've certainly seen that particular argument
many times going back decades.
Arved, Joshua, RedGrittyBrick, Arne and others have presented excellent
rationales for using Javadoc comments most of the time, if not nearly all the
time, whether for "application" or "API" code. They have also presented good
thinking about when one might reasonably not need additional Javadoc comments,
when appropriate alternatives are already in place.
Given the nearly effort-free nature of the insertion of such comments, given
most if not all Java editors' / IDEs' capabilities, one must conclude that
there should be a nearly overwhelming preference to Javadoc-comment all class
members. The Javadocs published from those comments should include all public
and protected members, since those are the ones available to client classes.
--
Lew