API design values and decision matrix

We’ve come to a nice way of deciding upon features in the Isolator API. This is what happens when your end product is an API for programmers.

First, we realized that we must argue about it. For each type of new feature in the isolator API, we put up on the white board several version of the API that we can’t seem to decide about, and then ask everyone on the team to say what they think. If everyone agrees, then we ask people to defend the opposite side and explain why an API is not good.

We came to several agreed upon values for the C# API, that help us judge the usability of it:

• Consistency – is the new API consistent with the other APIs that already exist, or does it go against the regular way things are done?
• Discoverability – If a user knew they wanted to do thing X, would they know to use the API without help? simply from intellisense?
• Explicitness – we decided early on to be as explicit as possible about the API, so that the least guessing needs to take place by the user
• Single point of entry – everything should start from a single point (Isolate.Something())
• Readability for the reader, not the writer (if you didn’t write the test would you find it easy to understand what it does?)
• Single way to achieve things – is there more than one way to do a task with the new API?
• Backwards compatibility – do we break an existing feature and cause some heartache  for users?

We measure the various versions of an API by putting it in a matrix and setting “V” or “X” on each of them (if we can’t agree it’s a V with a line on it).

then we have a better idea of what makes more sense.

I admit we still haven’t come up with a single set of values for the VB API, but I’ll try to define it here:

• Does not require use of Action<T>
• Consistent with the way a VBer would use other APIs
• Explicit
• Readable
• Single way to achieve things
• Backwards compatible

note that “single point of entry” is not included. That was a design decision we made early on.