begin quoting Darren New as of Sun, Mar 16, 2008 at 08:39:53PM -0700: > SJS wrote: > >This is why I like Java's Javadoc... method-level documentation, class- > >level documentation, and module-level (or package-level) documentation, > >all derived from the source tree. > > First, it still generally doesn't help if stuff spans more than one > module.
Packages nest quite nicely, which is an appropriate level for that sort of documentation. If you have a project where the modules have undue levels of coupling and poor cohesion, then no amount of documentation anywhere will help. > Try to learn (say) J2EE by reading module-level documentation. Using J2EE to criticize Java is like using C++ to criticize C. J2EE is an unmitigated mess, and from my point of view, it's designed for one thing only -- to give IBM, HP, BEA, etc., a nice high-priced product to sell, and to encourage sales of their high-priced software modelling tools. As far as I'm concerned, it's the wrong approach to the wrong problem, and the only thing keeping it from being the worst-possible way is that it's not self-modifying code. > Second, most of the stuff I've seen is documented like this: > > void blarg(int arg) > Blargs the arg. Well, yeah, bad documentation sucks about as much as bad code. And I've written my share of bad documentation. Sometimes, it takes more time to write a decent comment than it takes to actually write the code and the unit tests combined. > Indeed, the early Java stuff was documented like this: > void read(buf) > Reads the buffer > void write(buf) > Writes the buffer > because they didn't bother to change the copy/paste errors in the source. How early are you thinking of? Java's documentation has been reasonable for as long as I have been using it... it's the more RECENT stuff that's getting useless. > At least when you're actually sitting there and writing documentation, > you can think about something *other* than the code. Which is why it's often poorly written. :-/ The number of programmers who can also write is vanishingly small. > Granted, it doesn't have to be bad. But in my experience, any library > that gives you *only* auto-extracted documentation has suckalicious > documentation. Anyone doing serious development for useful libraries > does the documentation first, and something winds up without a good > place to put it in the code. In my experience, most projects provide suckalicious documentation. The ones that provide externally-written-and-maintained documentation have extremely misleading or useless overview documentation, while *some* of those who provide javadoc-only documentation (using package.html files) approach halfway decent. My experience has generally been with custom software, so my sample set is no doubt a bit skewed. I often integrate with semi-hostile projects. -- All software sucks, and that is the crux of why software is hard. Stewart Stremler -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
