Making an API Hard to Misuse

Rusty Russell (of Linux kernel hacking fame) has been spending some time recently thinking about what makes for a good API. His first article on the subject was APIs: "Easy to Use" vs "Hard to Misuse", where he pointed out that the subtlest requirement for a good API is that it be hard to misuse.

He's continued this theme in his latest post, How Do I Make This Hard to Misuse?, he discusses one aspect of the matter: not how to write a good API, but how to create one that's hard to misuse. Anyone who develops software for a living can tell you that "easy to use" does not necessarily mean "hard to misuse"!

Rusty puts together a "hard to misuse" scale that starts at "It's impossible to get wrong". It's interesting that, as you go down the scale, there's a transition from "hard to get wrong" to "hard to get right". The worst possible state you can be in, at least by this scale, is "Read the correct mailing list thread and you'll get it right" - in other words, an API that is so difficult to use that you can't make it work without some form of expert guidance.

As with a lot of articles of this type, the value isn't really in any one particular suggestion. If you're a software developer, you'll read through this and think, "Well... yah. Sure. I do that." You might find one or two items at the top of the list that are new to you; but that's not what caught my attention. Instead, the real value of the this article is in getting you to think about an old problem (API design) from a different point of view - something that's almost always worthwhile.

No comments: