Chapter 5: Do not expose more than you want

(pag. 69)

There are many attributes of good API design, and this book will discuss many of them. But let’s start with the most trivial advice. This advice is widely known, explained in every good design book, yet so important that it deserves to be repeated all the time: the less you expose, the better.

Some API designers just love helping others and believe they’re doing so by putting a lot of helper methods and utility classes in their API. They make every class public. A lot of their classes have members that are either public or protected. These designers believe that one day someone might find their exposed functionality useful. Though there’s nothing to be said against altruism, these designers often cause more problems than they solve. Always remember that it’s much easier to add a new class or method to an API than to remove it. Furthermore, the more you put into an API, the more you have to maintain in a compatible way. The more that’s visible, the less flexibility you have in changing the internals of the implementation. Exposing more than is needed can, in fact, prevent future improvements in the API. Fundamental dilemmas involve deciding whether something should or shouldn’t be part of an API. The answer to that, at least according to the NetBeans project “methodology,” is to construct <use cases>. A valid <use case> is the justification for a class or a method in an API. If there’s no <use case> for a given method or class, or if the <use case> is slightly suspicious, then it’s better to leave that element out of the API. One way of doing so is to make it package private. When a user of the API complains and requests the element to be visible, you can still make it visible. However, don’t do so sooner than requested and not without a convincing <use case>!

THE LESS SKILL, THE MORE VERBOSE THE API

My experience shows that the less skilled an API designer is, the more elements the API exposes. In many cases, this can be attributed to a lack of understanding of use cases. Lack of understanding results in making an existing method or class public whenever some functionality from a library is needed. This style of evolution, where there is no strategy at all, will almost certainly lead to a set of isolated API elements that are randomly glued together. An absence of use cases indicates a lack of strategy and leads to a cluttered result. Less experienced designers, lacking the wisdom that comes with maintaining an API over several years, often don’t realize that everything they leave in an API can get misused. Every method and class exposed by an API will be misused—in other words, used in a different way than intended by its author. Almost every API designer I know has observed this to be true. And almost every API designer has come to the same conclusion: the longer you spend designing an API, the less you are willing to expose.

So, the first piece of advice is to remove everything that can be removed prior to the first release of an API. Realistically, not everything will be removed as a result of this advice. Behind every altruistic will to share there has to be some hidden need—something that drives and motivates the API’s design. The API designers feel the need for their work and they are eager to share it. I know that feeling; I’ve felt it many times. It feels good; however, you need to keep in mind that publishing an API is just first the step. By publishing it, you promise to do much more in the future. You promise to develop the API compatibly, to maintain it properly, and much, much more. In fact, by taking the first step you set a direction and promise that every other step will follow that direction. There’s nothing wrong about taking such a step if the API designers feel there’s a need to create the API. On the other hand, we need to learn how to prevent promising “directions” when we’re just “walking.” The simplest and most effective solution is to hide the fact that we’re taking steps from our end users.

A Method Is Better Than a Field…(cont.)