Statically Typed

because Hindley-Milner rocks

Bad API Design


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:

  1. To accomplish a single task, does the invoker of your API have to repeat themselves? — Think of it as dialing your local bank.  Remember a few years back when you’d have to listen to the phone bitch, punch in your SS, punch in your back account, punch in your zip code, state your name and then when you finally got through call waiting you’d have to do it all again?  Don’t be a phone bitch.
  2. Is your nomenclature consistent?  Do you have get, Get, get_ and Get_?  Or is it get, retrieve, or return?  Does one return a value while another returns a parameter through the parameter list?  Can you even remember which one does what?  They won’t.
  3. Are things well separated or did you go too far?  Do you have a ProcessingFlag object that returns the user, OS, if a run is started, if its ended, and maybe a server socket object?  Or is there a DatabaseConnection object that is used with a DatabaseName, DatabaseType, DatabaseQueryStyle, DatabaseLocalization, and DatabaseConnectionCount each with but 1-2 methods?  On one hand no one likes a “God”-class but they also don’t want to deal with a “Serf”-class either.
  4. Do the methods infer by their naming conventions functionality they do not posses?  Could they be subject to interpretation?  Coming up with a ServerReset function might sound great to you.  I read it as a programmatic power button.  It must.. reset the server!  Perhaps a DisconnectAllUsers would be more appropriate.
  5. Do methods of a class imply that they should produce nearly identical functionality?  That is, a call to “getCurrentUser” is more than likely expected to yield the same as “getUser( User.CURRENT_USER ).”

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.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Information

This entry was posted on September 7, 2010 by in Uncategorized.
%d bloggers like this: