The Naked Flame

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.

I do a lot of thinking when I am not developing libraries of abstractions in the hope they will make my (and my colleagues') work easier in the future. When I think I mainly think about how to make things better / easier / more foolproof.

Just recently I have seen the light of Dependency Injection as a solution to a problem that Steve Yegge is convinced does not exist (although from his comments on it I suspect he may have only seen a good idea mis-applied; I wholeheartedly agree with the main thesis of his post).

Via the vessel of NInject I have been exposed to the concept of Fluent Interfaces, how they (don't?) relate to DSLs, and tons and tons of misconceptions about the usefulness of Fluency as an API design choice under the right circumstances.

And all this has mushroomed into a Wikipedia-like meandering about topics of API design, only to come to the conclusion that there doesn't appear to be any well-reasoned discussion of how to come to a good API that does not involve trying to mesh several partially-orthogonal and incomplete discussions.

Maybe I am missing a site containing the holy grail somewhere. Not being able to find it however, its existence is indistinguishable from it's non-existence, so the best I can do is try to figure it out for myself.

As I go along digesting information I am going to try and build a series of "API Design Research" posts referencing the sources I am reading and my opinions and "lessons learned". Hopefully this will all end in one or more posts distilling it all down to practical advice, mainly for myself, but hopefully useful to others as well.

Disclaimer: I currently operate in a C# .NET universe, and as such, all my discussions will be biased towards what makes sense in that context. I am sure some of my conclusions are not going to be valid in "language X" for your favourite value of "X"... I am sorry, but I also do not care.