97 Things Every Programmer Should Know

Chapter 35. The Golden Rule of API Design

Michael Feathers

API DESIGN IS TOUGH, PARTICULARLY IN THE LARGE. If you are designing an API that is going to have hundreds or thousands of users, you have to think about how you might change it in the future and whether your changes might break client code. Beyond that, you have to think about how users of your API affect you. If one of your API classes uses one of its own methods internally, you have to remember that a user could subclass your class and override it, and that could be disastrous. You wouldn’t be able to change that method because some of your users have given it a different meaning. Your future internal implementation choices are at the mercy of your users.

API developers solve this problem in various ways, but the easiest way is to lock down the API. If you are working in Java, you might be tempted to make most of your classes and methods final. In C#, you might make your classes and methods sealed. Regardless of the language you are using, you might be tempted to present your API through a singleton or use static factory methods to guard it from people who might override behavior and use your code in ways that may constrain your choices later. This all seems reasonable, but is it really?

Over the past decade, we’ve gradually realized that unit testing is an extremely important part of practice, but that lesson has not completely ...