I ran across a couple older items on API design: Words of Wisdom on Designing Usable APIs and Think of Objects as Machines.
good API designs happens when designers think of … client programmers as users.
I wish more developers took this to heart. I’ll add my own law of API design:
Good API design makes common things simple while leaving uncommon things possible.
You can call it Moore’s law. 
When comparing two API possibilities, I often just count characters in a couple common examples of usage. To me, the API choice that results in fewer characters for the client programmer is usually the better API. This can tip the balance for subtle choices, or help evaluate two libraries which do the same thing.
Feed
Subscribe to this blog…
Hi.
As an experiment the early versions of the SimpleTest API used TDD – Tutorial Driven Design. I wanted to write a mock object article and so wanted to add mocks to PHPUnit. I was working out the interface through the article. The problems I encountered caused me to write my own test case class and shelve the article for nearly a year.
Recently the API has been driven more by user requests, theft from the Java world (JWebUnit) and domain concepts (the web browser), but I am thinking that more than anything I should write another tutorial.
yours, Marcus
Tutorial Driven Design – you may be onto something. Seriously. Course it’s going to be hard for managers to swallow: “All coding begins… with a tutorial”
Maybe thats why I like SimpleTest so much. Designing the application by writing user documentation is not a new idea. I think that taking a tutorial oriented approach is a great idea because it focuses on the tasks that a user would want to do. User documentation that simply enumerated screens and menu items or that simply enumerated classes would not be good candidates for driving development. They are too much like the big design up front that the agile methodologies are trying to avoid. Writing tutorials doesn’t sound much different than writing stories. (use cases, essential use cases, scenarios or whatever you want to call them, I have a fondness for task based UI design.)
[...] was 15% less code (he was comparing compiled code size) and maybe 5% faster. Following my API Design principles, I think the smallest amount of c [...]
design by documentation is not new. The Sperry Univac 1100 mainframe operating system was not written until the reference manual had been written and approved.
It’s still a great idea. Anyone want to collaborate on a book?
Looking+for+information+
Great post! I never thought I would like ebooks but I’m converted. I have a ton and love writing them as well.