External Programming Interfaces
This article, by Eamonn McManus, is a nice little summary of API design principles. It contains a bit of motherhood and apple pie—nobody would ever set out to make an API difficult to learn or hard to use, for example—but the specifics are good (particularly the discussion of why interfaces are often the wrong thing to use). The article contains a link to this essay at the NetBeans site, which talks about some of the same ideas in more detail.
Together, the articles got me thinking: why don’t we ever talk about or document a module’s external programming interface (which I hereby dub “XPI”)? This is the classes, methods, and system calls that the module depends on; more particularly, it is their semantics. Design by contract allows a piece of code to specify what it provides; allowing that code to specify what it requires using similar pre- and post-conditions would be a big help in managing the asynchronous evolution of libraries that makes postmodern programming so hard.