Why Design Guidelines?

Many assume that the Design Guidelines document is intended to be a repository of the best solutions to common API design problems. Let me get it straight right away. This is not the intention at all. The main purpose of the Design Guidelines is to achieve consistency in reusable library APIs.

In a lot of cases, a reasonably competent API designer should be able to come up with better designs for their specific problems then those described in the guidelines, clearer naming conventions, or a more extensible way to expose a concept. But this is not the point. Customers have told us that in the majority of cases they strongly prefer consistency over novel designs. They perceive that for the most part such novelties as only marginally better and not worth the learning curve.

Anders Hejlsberg often describes it this way. You get -1000 points for being inconsistent plus 100 points for a better design. This leaves you with -900 points in debt to the customers.

This is easier to understand when you look at it from the point of view of an average programmer using your API, as opposed to looking at it from the point of view of the designer designing the API. API designers take pride in creating clever designs worth of technical praise. This is natural and quite desired characteristics of most software engineers. But the user of the API is unlikely to need, or even notice, the marginal difference between a good design and a slightly better design. This often requires being an expert in the field and most users are not, will not, and do not need to be experts in your field. What the user is mostly concerned about is having a familiar and a good enough tool to do their job. This is why the original paper clip is continuously voted the best design of all times despite that many “better” paper binding technologies have been invented.

Not to leave it on the boring note, there is place for revolutions in API design. The addition of Generics to the collection and other Framework libraries is one such example. Yes, there is a learning curve associated with the new collections and with the concept of Generics in itself, but we believe the improvements in this case are significant and they do significantly offset the negatives.