Josh Bloch - How To Design A Good API and Why it Matters

Guido van Rossum, creator of Python says, “Watch it at least once a year”.

This talk screams “Chinese philosophy” to me, everything from exemplar models to make right the names to learning (學) over thinking (思) to affecting the tips by taking care with the root. He even wrote up his findings as a series of aphorisms! I can’t tell if this is because they were right or because I read them into places where they don’t belong due to an over-application of the principle of charity to the originals in my interpretations.

The one point that seems to differ to me is that I can’t off the top of my head think of a parallel to hiding the implementation details of an API. I can see though why one would want to keep an API small, since one has to have trustworthiness (信, 誠, etc.) to keep the API working in the same way in the future. I guess that the reason for this difference is that in the social world, you shouldn’t try to refactor the underpinnings of some process, since things are almost never neatly modular. In computers, however, conceptual modularity is a fiction that can be maintained with a not unreasonable amount of diligence (though it does take some work; that’s why they say “Goto Considered Harmful,” etc.).

It may seem interesting that Guido, the creator of such a dynamic and plainspoken language as Python, should be recommending a talk by one of the creators of Java, a static and verbose language. However, the principles of good API design are more or less universal. What’s interesting about Java though is that because it is suited to use by large “enterprise”-type teams rather than an individual programmer or a small group of programmers, it more concretely embodies the social dynamics of Chinese philosophy. In Python, one ought to be a good citizen and use normal variable names and not monkeypatch and stay out of people’s private class/module members, etc., etc. But in Java these things are not just good ideas but absolutely vital practices. Having a large number of unrelated individuals (who are, to be honest, probably not the best programmers) attempt to work together on an enterprise application would be doomed from the start without the social straightjacket of classes, interfaces, public and private, “design patterns,” and so on to keep the masses inline behind the sage at the lead of development.