Usage code first: The right way to design APIs?

It's common advice, at least for those not sticking to TDD: "write usage code first". In other words, before you write an API, work out how you're going to use it.

In my experience this has been good advice. It's helped me write "conversational" code, that spells out exactly what it's doing, step-by-step. With minimal-syntax languages like Python, it's almost -- but not quite -- readable English.

As well as simple readability, it also helps maintain the atomicity of code. Writing near-pseudocode makes sure we're not clogging up business logic with implementation details, which should be placed in separate procedures. As a rule of thumb: it should be easy to describe what a function does in a single statement.

However, a major tradeoff is the mental overhead of multiple function calls to "atomic" procedures. Code is often read as well as written: deep function call chains may be difficult to understand for future maintainers. Time and memory overhead, on the other hand, are likely to be of little importance outside embedded or real-time systems.

It can also introduce inflexibility reminiscent of the Waterfall development cycle: once code is written in this style, it is often difficult to make changes to the algorithms underlying the project. However this may simply indicate a lack of atomicity in procedures.

It's likely a good solution for some projects, and a bad one for others. At the end of the day, it's just one way to help with writing good code!