Leave it out 🚫

One of my favorite pieces of advice on API design comes from Joshua Bloch. He is one of the architects of Java, father of the Java Collections Framework, and several books on Java. He says:

When in doubt, leave it out.

Easy to say. Often hard to do.

He elaborates on this and many other ideas in his article Bumper-Sticker API Design.

When in doubt, leave it out. If there is a fundamental theorem of API design, this is it. It applies equally to functionality, classes, methods, and parameters. Every facet of an API should be as small as possible, but no smaller. You can always add things later, but you can’t take them away. Minimizing conceptual weight is more important than class- or method-count.

This is very clear, no-nonsense advice. If you are not sure that adding something will make it better, leave it out.

One aspect that I feel deserves a little bit more focus is the idea of conceptual weight. When measuring what a “minimal API” is, the number of concepts the user will need to understand, is more important than the exact number of classes or methods. Otherwise, you may be doing the API design version of the “clever one-liner”, where way too much functionality is crammed into too little space.

The price for high conceptual weight is confused users. In fancier terms, it causes high cognitive load. As Artem Zakirullin points out in his article Cognitive Load is what matters:

Confusion costs time and money. Confusion is caused by high cognitive load. It’s not some fancy abstract concept, but rather a fundamental human constraint.

In my experience, if I’ve come up with a complicated API, it is often an indication that I haven’t fully grasped the problem yet. It is a sign to start over. To start with a basic API which nails the fundamentals. Then slowly add more things in as I find that I need them.

And if I find myself in doubt? I leave it out.