I have just read a very interesting article "API Design Matters" by Michi Henning. He discusses the problem with bad designed and gives some rules of thumb. We all have some time used an API that does not feel right and makes the coding hard. It is very interesting to read Michis analyze of this and why. My feeling is that he had put the hammer right on the nail. Here is a summary of the rules he discuss. I assume you will feel like me when you read them; yeah thats obvious. But thats the nice thing and the important is to get the list.
An API :
- must provide sufficient functionality for the caller to achieve its task.
- should be minimal without imposing undue inconvenience on the caller.
- should be policy free if it is general purpose.
- should be policy rich if it is special purpose.
- should be designed from the perspective of the caller.
- don't let the caller configure "everything".
- should be documented before it is implemented.
If you want to read the discussion behind the rules, go to the article.