because Hindley-Milner rocks
You know, there’s something fundamental to API design. It’s so very easy to screw up and so very hard to fix. However, one of the things I’ve striven to do when creating an API is to ensure that related function calls perform in related ways. There have been times when project deadline constraints have forced me to make some poor choices (I’d love to have the time to fix them.) So here’s my simple list of quick check-boxes to go over before submitting an API to a customer:
Why do I pen these five little things down you might ask? Today I was frustrated by my discovery of an all too expected (given the third party) gotcha when handling some requests with an API I’ve been forced to use at work. Have a gander at my interpretation of the pseudo code:
Point origin(CLSID_Point); origin.put_X( 10.0 ); origin.put_Y( 10.0 ); origin.setZ( 0.0 ); origin.putref_GeographicProjection( GeoProjection3::GeoProjWSG84_UTM ); ProximityOperator proximity2Polygon( &polygon ); //square, sides length 4, centered at 10.0, 10.0, 0.0 double poly2origin, nearest2origin; proximity2Polygon.shortestDistance( origin, &poly2origin ); Point nearestPoint = proximityPolygon.returnNearestPoint( origin ); ProximityOperator proximity2Nearest( &nearestPoint ); proximity2Nearest.shorestDistance( origin, &nearest2origin );
And for added effect: the shorestDistance function returned the distance from the closest point in coordinate space from one shape to another while the NearestPoint returns the closest point in coordinate space from one shape to the outermost edge of the other.
Ugh! It feels good to vent.