Keith Devens .com - Weblog: Obvious piece of documentation of the day

Sunday, August 10, 2003

Obvious piece of documentation of the day

From Java's FileInputStream, check out this insult-your-intelligence bit of documentation:

A FileInputStream obtains input bytes from a file in a file system. What files are available depends on the host environment.

Yeah, thanks.

Permalink | 1 Comment | Tags: Programming | id 4169

11:25 (utc-4)
edited: 14:26 (utc-4)

Comments

Reminds me of a jar of peanut butter I saw a while back - "May Contain traces of Nuts". No, really? People seems to get confused about code documentation. Good Documentation is good, bad/usless documentation is even worse. If the documentation is useless, people assume that all the documentation for that code is also useless and then don't read it. If the documentation is out and out wrong however (for example people not updating their pseudo code inline with code changes) it can be even worse - sending code maintainers on a wild goose chase.

Feel free to post a comment below. Please see my comment policy.

Formatting Rules (No HTML):

**bold**, *italic*, _underlined_, --strikeout--
"text"="url" creates a link, and URLs are auto-highlighted
Blockquote: Like e-mail, begin paragraph with > (greater-than sign)
Lists: begin paragraph with *,-, or + (unordered), or # (ordered)
Code block: ?!code:language=perl|php|sql|javascript|etc.{\n}...{\n}?!/code

RSS feed RSS feed for Keith's Weblog
Atom feed Atom feed for Keith's Weblog
Weblog archive
Recent comments
on 4 posts