Elliott Chen logo single outlinedElliott Chen logo solidElliott Chen logo text

Consistently bad is better than inconsistently good

by Elliott Chen, a developer

A while back, I poured my thoughts into a blog post about the struggle of maintaining consistency, emphasizing how it's a challenging feat in any profession. Today, my conviction about the importance of consistency remains unwavering.

Many people seem to overlook the significance of consistency, it is, actually, crucial.

In the software development, one thing that can make or break success is the design of APIs. APIs act as the glue that connects different software parts, making communication and integration seamless. While aiming for perfection in API design is commendable, there's a controversial idea that consistently having somewhat bad APIs might actually be more beneficial than having ones that are inconsistently good.

Perfection is like chasing a rainbow, especially in the API design realm where various use cases and evolving requirements keep things in constant flux. The pursuit of perfection often leads to overthinking, delays, and a reluctance to launch a product until every possible scenario is covered. On the flip side, prioritizing consistency in API design ensures that developers can foresee how different components will interact, creating a more stable and dependable system.

By consistently bad, I don't necessarily mean horribly designed APIs with glaring flaws. It's more about APIs that may not follow every best practice but stick to a predictable and uniform implementation. Developers lean towards a consistent, even if not the best, experience over an API that throws unexpected curveballs.

Picture an API that maintains a consistent naming convention, error handling strategy, and authentication method, even if they aren't the most cutting-edge choices. Developers working with such an API can quickly get the hang of it because they know what to expect. This predictability eases the mental load on developers, letting them focus on solving real business problems instead of deciphering the API's quirks.

In contrast, an inconsistently good API might introduce unnecessary complexity and variations. Developers find themselves repeatedly consulting documentation, troubleshooting unexpected issues, and tweaking their code to handle different scenarios. The mental gymnastics of dealing with an unpredictable API can slow down development, counteracting the benefits of its good design decisions.

Having consistently bad APIs doesn't mean throwing best practices out the window or ignoring the need for improvements. It's more about launching a version that meets basic needs and refining it over time based on user feedback and evolving requirements. This practical, step-by-step approach allows for continuous improvement while keeping the API's core elements consistent.

In the API design universe, the pursuit of perfection sometimes becomes a roadblock. Consistently bad APIs, approached with the right mindset, can offer stability, predictability, and an environment where developers can thrive. As the saying goes, Consistency is key. It's not about settling for mediocrity but recognizing the value of predictability and simplicity in creating a positive developer experience. So, when it comes to API design, maybe consistently keeping it simple is better than inconsistently going for perfection.


Maintaining consistency involves avoiding double standards.

More articles

ui = f(data)(state)

What UI means to when functional programming comes in.

Read more

Oh My Developer Experience

What I think DX is and how to improve it in a short-term and a long-term run.

Read more

Let’s talk.

My location

  • Elliott Chen | Studio
    Pudong APT #213
    Shanghai, China