Dave Donaldson

Brad Abrams posted the other day about a Dr. Dobb's Journal article titled "Measuring API Usability". It was written by Steven Clarke, a usability engineer at Microsoft, and is now available online here. As a person who thinks about and designs APIs a lot, I found this article very useful with good insight. A highly suggested read.

I find that designing APIs is quite a bit harder than most people think. In my experience, I've found that a lot of APIs were written for a particular team or project, without much thought of how the API might be used by someone else, which if you think about it, is the point of having an API. When I design APIs, I tend to only think of how other dev teams might use it. Sure it needs to be useful for me, but I know the API; other people won't, so I design with them in mind. I don't want to make other dev teams go through a bunch of documentation just to figure out what each method of the API does, especially when the documentation might be incomplete or wrong.

I first start out at the use case level and think about the scenarios involved. Then I spend lots and lots of time on the names of the methods. Determining proper names for methods of an API is a very crucial exercise. I write down every possible name for a method on my whiteboard, then narrow the field down a bit and begin writing sample code to get a feel for how easy/hard it is to use the methods for a given scenario. Writing the sample code is also critical because if you think it feels awkward or hard or messy, then chances are so will other people. I'll have some other people take a look and get feedback, then narrow the list down even more. At that point, the API has pretty much taken shape and I'll get some additional feedback to validate the design.