How Do I Make This Hard to Misuse?
Posted Mar 31, 2008 21:44 UTC (Mon) by ajross
In reply to: How Do I Make This Hard to Misuse?
Parent article: How Do I Make This Hard to Misuse?
I think that you're missing an important possibility: write really
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
to post comments)