97 Things Every Programmer Should Know

Chapter 19. Convenience Is Not an -ility

Gregor Hohpe

MUCH HAS BEEN SAID about the importance and challenges of designing good APIs. It’s difficult to get right the first time and it’s even more difficult to change later—sort of like raising children. Most experienced programmers have learned that a good API follows a consistent level of abstraction, exhibits consistency and symmetry, and forms the vocabulary for an expressive language. Alas, being aware of the guiding principles does not automatically translate into appropriate behavior. Eating sweets is bad for you.

Instead of preaching from on high, I want to pick on a particular API design “strategy,” one that I encounter time and again: the argument of convenience. It typically begins with one of the following “insights”:

• I don’t want other classes to have to make two separate calls to do this one thing.

• Why should I make another method if it’s almost the same as this method? I’ll just add a simple switch.

• See, it’s very easy: if the second string parameter ends with “.txt”, the method automatically assumes that the first parameter is a filename, so I really don’t need two methods.

While well intended, such arguments are prone to decrease the readability of code using the API. A method invocation like:

   parser.processNodes(text, false);

is virtually meaningless without knowing the implementation or at least consulting the documentation. ...