API design "theory" is curious, because it seems to take a back seat in the academic literature, and yet the economic impact of bad API design is so great to the "problem" of software development. I guess the Software Engineering folk are fighting the good fight with code quality metrics, etc., but this is a hard topic, that I had never considered throughout my entire undergraduate career.
Here's an example of an API design mistake in my opinion (albeit a simple one). In Java, there are the following constants defined:
These define the lowest value that can be represented by this datatype. Thus, for example, Integer.MIN_VALUE is -2147483648 given that its 4 bytes and uses a 2-s complement representation, etc.
These are used all over the place as sentinels. For example, a typical implementation of Dijkstra's shortest path algorithm initializes every node to a shortest distance of Integer.MAX_VALUE, and as the algorithm progresses, any value will (likely) be less than MAX_VALUE. Thus, it's a natural way to construct the algorithm without having to code a bunch of fragile "special cases" (adding to your cyclomatic complexity).
So what do you think Double.MIN_VALUE returns?
Well as a bug that I coded last week demonstrates, it does *not* return the minimum value of the range of values that can be represented in an instance of the Double data type. That would be ludicrous (this is me being sarcastic).
No, instead it returns the smallest positive value. You need to use Double.NEGATIVE_INFINITY for the smallest, *cough* minimum *cough* value.
Note that in C#/.NET Double.MinValue is the minimum value (i.e. negative number). I wonder what it is in limits.h...
So what's up Java?! I wonder how many man hours of time have been wasted on this pitfall since Java's inception? Can we ask Guy Steel and Bill Joy for a check? Just kidding...