Re: On Interfaces and APIs

[xdg]

++ for an amazingly comprehensive reference list.

However, in trying to absorb the 39 various bullet points of proposed guidelines on API design, I'm reminded of the Justice Stewart quote on pornography:

"I shall not today attempt further to define the kinds of material I understand to be embraced . . . but I know it when I see it . . . "

Of the various guidelines, I like Bloch's best because of the short and clear concepts they present. The others need to be parsed and understood and use several metaphors that impede clarity unless you already know what the authors are talking about.

Part of the challenge in giving API guidelines is that API style is context dependent as well. Different language styles lead to different API styles and what works best for one language might not work best for another.

For the reference section, I'd suggest adding things like Tufte's VDQI, as the principles he lays out for eliminating non-data ink have some nice parallels to API design -- particularly of the Conway style. On the other hand, sometimes, as with named parameters, clarity and extendibility means more ink (er, pixels), not less.

Separately, one reason that I like test-driven development is that by writing unit tests first before writing code, I wind up "using" my API before I implement it. At that point, the cost of change for the API is minimal. Even as code is implemented and additional features are added, the cost of change at that point is still pretty low. I'll frequently do several drafts of the API just while writing the test file.