This morning, a reference to a short and well written PDF written by an engineer at Trolltech/Nokia came through my feed reader. It’s only 33 pages long, and every one of those pages has solid guidelines, recommendations, and examples (both good and bad) of considerations you should keep in mind when developing an API of any kind:
This manual gathers together the key insights into API design that were discovered through many years of software development on the Qt application development framework at Trolltech (now part of Nokia). Whendesigning and implementing a library, you should also keep other factors in mind, such as efficiency and ease of implementation, in addition to pureAPI considerations. And although the focus is on public APIs, there is no harm in applying the principles described here when writing application code or internal library code.
- Easy to learn and memorize
- Leads to readable code
- Hard to misuse
- Easy to extend
- Complete
(and reading that list makes me think back on my years of writing C and C++ code using the WIn32 APIs and cry a little), but this document goes past that to outline a well-considered process for designing an API, and guidelines to follow when designing an API, concluding with the very Zen “The best API is no API”.
Do check it out.
The Little Manual of API Design
(image from http://sofa.projects.semwebcentral.org/doc/design/index.html)
