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 »