How Do I Make This Hard to Misuse?
Posted Mar 31, 2008 18:53 UTC (Mon) by ajross
Parent article: How Do I Make This Hard to Misuse?
I'm surprised to find a huge one missing: Don't provide two ways
to do the same thing if one of them is wrong.
Rusty is talking about kernel code, so I guess he might be assuming
a higher quality of developer than I am. But misunderstandings of
"thick" APIs is probably the source of more "API misuse" (and other
bugs and misfeatures) than anything else I'm aware of.
All library code has this disease to some extent or another (Java
has it like the plague), and 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. And since
they don't understand the library as a whole, they don't have a prayer
of understanding the tradeoffs and misfeatures that result from their
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, such that
developers don't get stuck using the wrong tool for the job. Choice 1
is clearly preferable but very expensive -- there aren't many
Option 2 seems like a much better choice. The only downsides are
that more "boilerplate" code must be written to make up for the lack
of "convenience" (ugh) functionality. And, I guess, there will be objections from
people who don't understand this "minimal" aesthetic and want to
choose the wrong solution from the choices offered by a much larger
Personal plug: here's my take on "minimal but complete"
functionality as expressed in a small embeddable scripting language:
to post comments)