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.
--
Darren New / San Diego, CA, USA (PST)
"That's pretty. Where's that?"
"It's the Age of Channelwood."
"We should go there on vacation some time."
--
[email protected]
http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
