Wandering Thoughts: Recent Entries For 2005/12/22

What I really want is error-shielding interfaces

Recently (for my version of 'recently'), the blogosphere had a little tiff about 'humane' versus 'minimalist' APIs, starting with Martin Fowler's article and continuing onwards (there's a roundup here). To caricature the positions, the minimalist side feels that APIs should have only the basic building blocks, and the humane side feels that APIs should have all of the commonly used operations.

(Part of the fun of the whole exchange is that it got framed as a Ruby versus Java issue, due to the examples picked.)

I come down somewhere in between, because I am nervous about the large APIs that humane design creates but I think that minimalist APIs offload too much work to the programmer. What I like is APIs with basic building blocks and routines to do the common operations that are easy to get wrong. Unfortunately I have no snappier name for this approach than 'error-shielding interfaces'.

For example, getting the last element of a list. Something like 'aList.get(aList.size - 1)' contains enough code that there's chances for errors, so I much prefer either 'aList.last' or 'aList.get(-1)'. As a bonus, they clearly communicate your intent to people reading your code without needing them to decode the effects of the expression. (I have a vague preference for the aList[-1] approach, because it clearly generalizes to the Nth-last element.)

Similarly, I think that Python's .startswith() and .endswith() string methods are great additions to the API. They're common enough, and they make sure no programmer will ever write a stupid off by one error in the equivalent Python code. (I've written it. And eyeballed it carefully to make sure I got it right.)

In Python, there's another reason to add common operations to extension module APIs: an extension module can often implement a common operation significantly more efficiently than Python code can. For example, the Python equivalent of .endswith() pretty much has to make a temporary string object.

(There's also Ian Bicking's contribution, more or less on interface design in general here, which is well worth reading and thinking about.)