There is an excellent article in the ACM Queue on API Design. Having given it a read through, what it’s describing is similar to how we’ve been working with Ewl.
We’ve sent a lot of time on the APIs. Nathan and I have exchanged countless emails, prototypes and test header files describing what we’re looking to do. We’ll often write test source files that use the interfaces to see how the ‘feel’ when being used. We spent a good couple of months working on the current MVC code that Ewl is using.
We spent a lot of time looking to get the most flexible design but not having it being terribly painful to use. I think we’ve struck that balance but it’s a test only time will tell.
With careful design of types and parameters, errors can often be caught at compile time instead of being delayed until runtime. Making the effort to do this is worthwhile because every error caught at compile time is one less bug that can incur extra cost during testing or in the field.
Catching errors early is a big one for us. Anything found at compile time can’t be a bug. Anywhere we can we use enumerations for your paramateres. The values are laid out with detailed names so you can see what’s going on just by reading the caller code.
The APIs are designed to be consistent (and inherit from other widgets as much as possible). We setup a naming structure and have religeously stuck to it (spending the extra time to break all the APIs that didn’t conform to the conventions).
The big convention that Nathan had in place before I join is that all callbacks
have the same signature.
void cb(Ewl_Widget *w, void *ev, void *data). No
matter what you’re doing that’s the signature. It makes it very easy to write
out function headers and fill in the bodies later. You never have to look up and
see what the signature is for a given callback. (The callbacks are, of course,
an enumeration so any errors there will be compile errors.)
Anyway, if you’re doing any API design I’d recommend the article. It gives a lot to think about and a few good examples of how things can go wrong and the cost to fix it when it does.