The Morning Brew

As a developer I am most happy writing code for other developers to write code with. I attribute this in part to the fact that I don’t enjoy writing user interface code as much as writing the code that no-one sees. For me, my favourite user interface is an API or even a web service.

One of my favourite books about APIs is Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Brad Abrams and Krzysztof Cwalina. I’ve been reading Brad’s Blog for quite some time and today he posted a link to a really good presentation by Joshua Bloch about designing good APIs. The presentation is video with the full slide deck, and covers a range of topics from the initial specification of an API, through implementation considerations with some specific references to good and bad APIs. I found the parts about specification of an API and avoiding implementation details leaking into the published API and controlling the interface of the API.

Things I took away from watching the presentation:

• Consult people about the specification – get as much input as possible before committing to a design
• Keep the interface simple – over complication makes using the API confusing – Usability is important for APIs, stick to naming conventions already in use for your platform
• Control what you expose – don’t let internal implementation escape through your API, control the exceptions and types you expose
• Documentation is important – make sure all public parts of the API are documented, the level of reuse of your API will be defined by the how good the documentation is
• Consider performance of your API – make sure its not going to cause any horrid performance characteristics
• Subclass only when the type is really a sub class of the parent type (Liskov Substitution Principle)
• Don’t make the client do work if the module can do it for you – avoid the need for boiler plate code to use your API
• Report errors as early as possible – compile time is best, runtime is worst
• Be careful about your parameters – use the most appropriate types, keep the number of parameters under control, make sure overloads are obvious
• When throwing exceptions give as much information about why the error occurred as possible

The list above is not exhaustative, I highly recommend watching the full presentation – its well worth the 68 minutes it will take.

3 Comments »