How Do I Make This Hard to Misuse? [LWN.net]

How Do I Make This Hard to Misuse?

Posted Mar 31, 2008 21:31 UTC (Mon) by rgmoore (subscriber, #75)
In reply to: How Do I Make This Hard to Misuse? by ajross
Parent article: How Do I Make This Hard to Misuse?

what it means in the real world is that coders with limited understanding of the library as a whole go thumbing through the documentation looking for a gadget that does what they want, and then plug it in, all the while failing to realize that another gadget would have been a much better choice. ... The solutions to this are either (1) make developers understand the design of the libraries they use at a deep level, or (2) write libraries with a minimal but complete feature set,

I think that you're missing an important possibility: write really good documentation. Sometimes you really want a dozen gadgets, each of which is different from the others in some small but important way. That's a lot less likely to trip up your users if you:

Group closely related functions in the documentation, so that it's easy for users to compare the different functions and pick the best one,
Cross-reference the functions, so that anyone who reads the documentation for functionA also knows that there are closely related functionA1, functionA2, etc., and/or
Provide a high level overview of the functional category, complete with a discussion of the differences between the functions and when you might want to use one instead of another.

I know that when I'm writing documentation for closely related functions, I try to do some or all of these. It's very helpful when coming back to use something I wrote a few years ago to find notes like "function_A does not guarantee that data will be written in any particular order. If output order is important, use function_B instead."

(Log in to post comments)

How Do I Make This Hard to Misuse?

Posted Mar 31, 2008 21:44 UTC (Mon) by ajross (subscriber, #4563) [Link]

I think that you're missing an important possibility: write really good documentation.

I limited my treatment to techniques that have been proven to actually work in practice. :)

Seriously: what you describe would be great. I've just never seen anything like it. At best (or at least the best I've seen), you get documentation like what Sun provides for the JDK: a very clean, readable, hyperlinked guide to a true rats nest of a library that only a tiny elite class of Java gurus actually understand.

The core problem being that great documentation does nothing for those who don't read it, and the sheer size of modern libraries guarantees that users won't read the documentation. You can get around this by finding developers who can read and distill only the core architecture from the effusive documentation, but then you're basically implementing a version of my "option 1" above.

For that matter, good developers tend to get the least relative benefit from all that "convenience code" anyway, and are happy to write the 2-3 lines of boilerplate needed to turn their iterator output into an array, or vice versa, etc... Which means that even given a guarantee that only talented developers will use your library, you're still better off making it minimal than you are adding functionality.

How Do I Make This Hard to Misuse?

Posted Mar 31, 2008 22:12 UTC (Mon) by nix (subscriber, #2304) [Link]

Oh, believe me, even when I describe exactly what functions do in the 
header files, complete with examples... they *still* don't get read, or 
people read the first line and ignore the DO NOT DO THIS in screaming 
flashing red with associated MIDI of a screaming police siren (or the 
closest I can get to that in source code). If I make whateveritis not 
compile if misused, it gets hacked by someone else so that it *does* 
compile when misused, because 'that was easier'. (No it bloody wasn't.)

Given that I work in the financial sector I'm tempted to see if I can 
write something which if misused in an unlikely way transfers the contents 
of the misuser's bank account into mine, and document this as a failure 
mode. I'd be rich within the week! ;}