The real cost of ignoring API design

The advice here is unglamorous, which is probably why it gets skipped. Nobody bills you for neglecting API design. The cost shows up somewhere else.

Most development decisions are really maintenance decisions wearing a different hat. If it only works because one person remembers to do something, it does not work yet.

Where the cost lands

• Time spent on work that should not have been necessary
• Enquiries that quietly never arrive
• Consistent naming saves every future integrator hours
• Rework, once the problem is finally visible

Version the API before anyone else depends on it. In practice this is a scheduling problem more than a technical one. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

What to do next

Errors should be as well designed as successes. Where this goes wrong is almost never a lack of knowledge. The version that survives contact with a real deadline is the simple one.

What this looks like day to day

Code gets read far more often than it gets written, and usually by someone with less context than the author had. Three things worth confirming about API design before you move on:

• Someone can say what the current setup is without going to look
• Consistent naming saves every future integrator hours — and you know whether that is true here
• There is a way to tell whether the last change to this helped

If you want a second opinion on how yours is set up, ask.