Coming from a .NET perspective, the place to start this journey is obviously Microsofts' Design Guidelines for Developing Class Libraries and the blogs of Krzysztof Cwalina and Brad Abrams. I have read most of this material before, but I think it'd be a good idea to refresh my memory before adding any additional material to the mix.

What also occurred to me as I was thinking this journey through is that a lot of the advice I will find should lend itself to static code checks. I would sincerely hope that StyleCop and FxCop already cover most of the material on "API Design" by Microsoft, but there may be gaps. Moreover, any additional materials I add to the mix after the basics is almost certainly not going to be covered by these tools.

What this means is that I hope to build up a list of rules as I go along which with some luck I might be able to implement as honest-to-goodness static checks so that my APIs henceforth will always be perfect (within some value epsilon).

As such I will need to keep a list of all the "rules" and "guidelines" that I come upon and carefully classify them along the axes:

  • "objective" / "subjective"
  • "always true" / "usually true" / "sometimes true"
  • "all APIs" / "specific types of API"

I think I have a serious amount of work ahead of me.