Designing Good API

Kode Vicious in ACM Queue has something interesting to say on designing good API. Some excerpts:

The first problem is that certain things, which ought to be passed as arguments, are encoded into the function name itself.

The next problem with this set of APIs is that they are very likely going to be implemented by a set of copy/paste operations....When code is copied and pasted thoughtlessly, bugs are replicated and then are harder to fix.

Human short-term memory has, on average, seven places to store things. If you're going to ask people to remember something extra, you better have a very good reason for doing so or they'll soon forget

API design is an iterative process. First you provide what you think the users need, as well as an escape valve such as ioctl. After a while you see which functions people are providing via the escape valve and you standardize those in your library as full APIs. Repeat until done.