It takes a long time to learn an API. Especially in the Java world, where a lot of Open Source frameworks are out there. Beside the documentation, also the API is an important factor whether a framework success or failure. It heavily depends on developers experience how easy to handle with the API. Are there any best practices out there to design good APIs? I think there are many start points to design good APIs, e.g. naming or provide small APIs. But there are many other factors influence really good APIs. The ACM queue published an article called API: Design Matters, analyzing apsects of good and bad APIs.
There is also a very good presentation about How to design a good API and why it matters, hold by Joshua Bloch. In this presentation, he assumed why good APIs are important, e.g.:
- Many people work with API
- People invest heavily: buying, writing, learning
- Successful public APIs capture customers
- and as I mentioned before it contributes to the success of a product/technology
- Easy to learn
- Easy to use, even without documentation
- Hard to misuse
- Easy to read and maintain code that uses it
- Sufficentily powerful to satisfy requirements
- Easy to extend
- Appropriate to audience
Additional to the above mentioned characteristics an API should also be good documented by using JavaDoc in case of Java. Why JavaDoc? The javadoc goes hand in hand with the development of an interface and is easy to update. It just depends on the developers discipline. The presentation provides a really good starting point by explaining how to write good APIs. He always provide short code snippets as a discussion base. Check out the article and presentation, and learn how to write good APIs.
No comments:
Post a Comment