Opinion: The API From The Black Lagoon

[In this reprinted #altdevblogaday-opinion piece, Q-Games programmer Ben Carter talks about "a widely-deployed and commonly-used example of every kind of Worst Practice in API Design".] Sometimes you meet an API which really just defies all sensible logic. You pass data as a comma-separated list here, but it wants tab-separated over there. Whitespace is ignored, except when it isn't. Things get renamed half-way through – one moment you're manipulating a widget object and then the next it wants an array of doodads. Which are the same as widgets, except for this one corner-case where they're actually thingies. Response times are critical – fail to pass something over promptly enough and internal timeouts will trigger all manner of unpleasantness… which is ironic, given that extracting even the most simple piece of data out of it can take hours. And even then, making the same query again will return different results depending on the time of day, phases of the moon, and how many times you have performed it. Sometimes you just cannot avoid using such an API despite it being obviously badly designed, badly behaved, and badly in need of rewriting. In those cases, the only sane option is to encapsulate it, surrounding it in the coding equivalent of a lead box from which none of its corrosive horror can escape. To not do so means that slowly but surely the rest of the code-base will become a mountain of special-case hacks, workarounds, and unfathomable magic numbers. Now, here's the unfortunate bit – there's a widely-deployed and commonly-used example of every kind of Worst Practice in API Design that most software cannot avoid at some point coming into contact with: Human beings Which is why, to bring this article (rant? irrelevant diatribe?) to a close by answering the question that prompted it, UI Code Is Pain Incarnate. No matter how simple it at first seems, the nature of what it has to talk to means that it always ends up growing beyond all reasonable expectations, generating more bugs than anything else, and generally causing havoc around it. So, grit your teeth and start building the lead-lined box early, because you're going to need it… [This piece was reprinted from #AltDevBlogADay, a shared blog initiative started by @mike_acton devoted to giving game developers of all disciplines a place to motivate each other to write regularly about their personal game development passions.]