API headaches

As a programmer, you sure have your favourite API-thrashing story. You know, the one where a destructor fails to release memory held by the object, causing an innocuous leak that is only caught when a million-dollar contract is at stake. The one where you need to call a function twice to use it once. And the one where you sacrifice your types at the altar of someone who thought it would be fun to use void pointers in a public interface.

API design is notoriously difficult. This paper says why. Suffice to say that the task of balancing conflicting requirements, for instance, of power v/s ease-of-use, along with constraints imposed by the target language, by the large (unknown) user base, and of issues like maintainability, extensibility, and performance - you have hell on your hands.

Still, I can't help but wonder why the APIs I use on a daily basis have the flaws they have. Why, for instance, does the Linq Aggregate function throw an InvalidOperationException when I pass an empty list to it. Why, for instance, the DateTime class does not comment what its MinValue is, beyond saying that it is public, static, readonly, and is the minimum possible date. Why, for instance, should the Enumerator be modified to check for end-of-container.

I have similar problems with some language features. The illogical distinction between structs and classes in C#. The whole mess created when operator overloading (specifically, op ==) meets reference equality.

I'm just venting. The C# language and the .NET runtime have amazing utility for programmers and have replaced native C++ as my choice of programming language.