Programming is like sex. One mistake and you have to support it for the rest of your life.
~Michael Sinz
I was in the process of reviewing some documentation for a bit of popular legal software my employer purchased a while back, when I stumbled upon an interesting tidbit. I recognized it immediately for what it was, but I'll get into that a bit later.
This particular vendor provides a RESTful API into their offerings. When invoking several of said API's methods, you can specify, as a parameter, a contactId in either one of two formats, termed Windows and Web.
The Windows format looks like this: 2/2195. Essentially two numbers delimited by a slash. Easy enough!
The Web format, on the other hand, looks like this: 8589936787.
So, to call their RESTful findContacts method, I would pass one of these two formats, thusly:
http://…/findContacts?contactId=[insert contact id here]
Reading further, I discovered that the Web format is actually a fancy calculation computed against the parts of the Windows format, thusly:
- Source ID = 2
- ID = 2195
- Web ID = (2 * 2^32) + 2195
The result of that calculation would give us the longer Web format: 8589936787.
According to the documentation, this was recently added as a "feature", which I suppose could be marketed as "slashless Web Ids". But, as far as mine eyes can see, really adds no value to the application.What it does offer is oodles of cyclomatic complexity, the extent of which may not be apparent at first glance. Let's take a closer look:
- Following this change, all developers on the project need to be educated that IDs can be input in two different ways. Why do they need to be aware? So that they don't assume that all IDs going forward will contain a slash, and can revise the way they handle ID input. Maybe they need to call a different function to parse IDs. Maybe they don't need to do anything at all. But I'm betting that somebody, somewhere, will either need to send an email about this change, spend an hour discussing it in a meeting, or add it to the project's internal documentation.
- The test cases developed before this change are no longer valid for testing ID input. Now you have to test the case where ID input doesn't contain a slash (the Windows format), as well as the detection of the ID input format (i.e. running different code based on whether the ID contains a slash or not).
- In this case, a new web method was developed, convertDualId, which does the math for any math-challenged developers out there. Something else that needs to be tested.
- The documentation I'm reading contains three (3) HTML (.chm file) pages of documentation on this topic, explaining the difference between the two formats, and how to do the math to calculate the Web Id if you don't want to call the new convertDualId method. All of which needs to be validated, proofread, and so on.
And all that for... what? Seriously. To calculate the Web Id, I still need to have the two original slash-delimited values, so what am I gaining? I'll tell you what I'm gaining: an id that doesn't contain a slash.
Woop-te-doo.
If a slash is bothering you that bad, I can think of several other much simpler alternatives. Like, say, just HTML-encoding the thing as %2F. But of course that wouldn't properly showcase the developer's creativity, virility, and prowess.
And therefore I must conclude that what this is, in fact, is gold plating at its finest. An anonymous developer's proud signature, showcasing his unique ability to do maths.
Hardly aware is he that writing code like this is akin to locking a ball and chain around his ankle, forcing him into supporting this unnecessary code until the end of time. Or at least until he realizes what he's done and leaves for unspoiled pastures.
Keep It Simple, Stupid.
