3 ms·
Personally I find that the sample code is often the most important part of the library. I like to learn by doing, and rewriting sample code into my own style is
by pavlov 17y ago
Personally I find that the sample code is often the most important part of the library. I like to learn by doing, and rewriting sample code into my own style is a great way to do that.
It needs to be supported by high-quality documentation, of course - preferably there should be a walkthrough of the code with relevant documentation links that go into more detail to explain the thinking behind the library.
What I really hate is documentation that's obviously written by technical writers who understand the concepts in the abstract, but have never written any code using it. It's frustrating to wade through pages and pages of patronizing explanations when a real-world example would do the job so much better.
(The worst example of this documentation genre I've ever seen is probably Symbian's C++ API documentation. First they spend an eternity justifying their pseudo-Hungarian type naming convention. Then they introduce a class hierarchy of a dozen classes for basic buffers and strings, dither over all the irrelevant details of the implementation, and claim that it's an "elegant example of object-oriented design". I guess they expect their audience to be of the captive kind that is forced to sit in a class room for a few weeks listening to trivialities, so it makes sense to waste all that time going over outdated '90s buzzwords.)
- aaronblohowiak 17y agoGood documentation includes examples. That's why `man` pages have an EXAMPLES section. The point you seem to be making about documentation organization being driven practically instead of horn-tooting, I completely agree with.
- pavlov 17y agoSorry if my point was so unclear. I agree completely that examples are an integral part of documentation. But it sometimes seems that this point is lost on the programmers and tech writers who should be collaborating to produce the documentation (or perhaps management is to blame for treating these roles too separately). The result is often documentation that's too verbose, too rigidly structured according to the implementation's hierarchies and doesn't match the thought processes and expectations of the target users.
- aaronblohowiak 17y agoRight, and I was similarly unclear. I think that examples should be interwoven with the documentation, and I think that your insights into the systematic reasons for this are spot-on.
- stonemetal 17y ago>>Good documentation includes examples. Should be: Good documentation includes good examples. Most example code out there is the worst code I have ever seen. Typically it looks like something someone slapped together in 5 min. Removing error handling to "improve clarity" just means that there are no examples of what errors the author of the library actually thinks are important or how to recover from recoverable errors.
- DougWebb 17y agoI agree completely, and this is what I _dislike_ the most about Java libraries. Far too much Java code that I've seen has relied entirely on what Javadoc can produce automatically from a codebase that does not contain lots of hints and extra documentation. A listing of classes and their methods is not even an adequate reference guide, let alone an adequate explanation of how to use the library and why it was written the way it was. As a counter example, I find that most perldoc documentation on CPAN is pretty good, because the standard practice for Perl module documentation is centered on the documentation sections that should be included _other than the list of methods_. NAME, SYNOPSIS, DESCRIPTION, USAGE, AUTHOR, SEE ALSO are all standard sections, and the kind of stuff that javadoc normally generates is just a subset of USAGE.