Here’s a clue that your API stinks

I was doing some development recently using Rocky Lhotka's excellent CSLA framework.  This framework lets you easily connect multiple tiers of an application with HTTP Web Services, WCF, Remoting, or Enterprise Services (you can even change transports just by changing your config files - cool!).  In my case, I was using WFC, and I had occasion to change a value in the config file.

The next thing you know, i was looking at this error box (just to be clear, this is a WCF error - not a CSLA error).

Now, in this case, the error message led me right to the source of the problem, so A+ for the efficacy of the error dialog.  D- for the API, though.  If you already know that two values in the config file have to be the same,

[Pause for effect]

Why... are... there...

[Another pause.  At this point, I'd like you to picture Lewis Black belting out this last bit, his outstretched finger pointed toward Redmond and quivering slightly.  If you're not a Lewis Black fan, use Jackie Gleason from Smoky & the Bandit.]

TWO   CONFIG   VALUES???

I'll allow for the possibility that this was lots more cathartic for me than it was for you, but I think you've got the picture.  If you already know the answer, then don't ask me the damned question, ok?  If you already know that both of these config values have to be the same, then one of them has to die.

The point in all this ranting is that API's have usability, too.  If your users are developers, and you do things in your API that frustrate your developer-users, they're not going to be big fans of your product.  Microsoft has traditionally been head-and-shoulders above the competition when it comes to API usability, and I truly believe this played no small part in the rise of Windows.  A better API means developers will enjoy writing for that platform, which implies more apps for users and more success for the platform.

Ignore this rule at your peril, though, because unhappy developers will avoid your platform whenever possible, and you'll soon find you don't have nearly as many people complaining about your API anymore.

Or, you could try this: