begin quoting Darren New as of Sun, Mar 16, 2008 at 07:07:54PM -0700: > David Brown wrote: > >A lot of modern languages are getting pretty good about solving both of > >these problems. The code stays as the definitive description, and the > >documentation is generated from the code. > > My experience with this sort of system is a complete lack of overall > introductory documentation. For example, sit down with the man pages for > bind(), listen(), socket() and related functions, and see if you can > figure out what's going on without already knowing how sockets are > supposed to work. Or sit down with some .NET classes and see if you can > deduce why every class says "instance methods are thread-safe, but class > methods aren't," and what you're supposed to do about it. > > Any system big enough that you need multiple modules full of classes is > going to need some documentation outside of every class. > > Otherwise, you wind up like people trying to use MS Word for a large > writing project without having any idea what styles are, formatting > every line separately, because the overall structure of how things are > intended to work is opaque.
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. Of course, having all that capability doesn't save you from having to WRITE the documentation.... and what isn't written even when easy won't be written if it's difficult to do so. -- Unit tests can help in the how-to-use, if not the why-to-use sense. Stewart Stremler -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
