(^38) 97 Things Every Programmer Should Know
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, exhib-
its 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 consult-
ing the documentation. This method was likely designed for the convenience
of the implementer as opposed to the convenience of the caller—“I don’t want