Implicit code needs explicit documentation

You'd think that I'd have learned from seeing perfectly valid code subverted time and again by folder/file/database permissions that weren't what I thought they should be. But that's not the only thing that can produce huge disparities between code that seems to be executing and the reality that comes out on the other side.

In today's case, that had to do with the fact that an order submitted into a system was listed as being paid by Visa, regardless of the payment method actually selected on the web page. What was actually going on under the proverbial hood was that the database table was expecting one of a fixed list of specific values (known as an ENUM data type) for one of its columns when the new record was inserted. But the code in question, as it turns out, wasn't specifying a value, and because the table was set up not to take a NULL value for that field, the database--logically, to my way of thinking--automatically picked the first value in the list and ran with that.

Luckily for me, I've already been bitten by auto-magical behavior from other databases, so I had the gut feeling that something similar was afoot. One peep at the database setup and another at the database documentation smoked out the "gremlin." But I wonder how much time a more novice programmer than I could have wasted on debugging--typically a clumsy process in PHP, more so this highly modularized PHP code-base. A little internal documentation would have gone a long way in that case. Even in my case, it would have solved the mystery that much sooner.

Ultimately, documentation is an investment: Spend a little time up front and maybe a little incremental time when code's updated, and the dividend comes every time someone has to make a pass through the code. Which, in my experience, happens more often than when than code's actually changed. Quite typically, the person reading the code just needs to understand what's happening upstream or downstream of what s/he's working on. That alone is enough to insist that any "implicit" code execution--i.e. those auto-magical side effects--be specifically documented. If you don't think that your programmers have time for that, than you'd better allow plenty of time for programmers to scratch their heads when unexpected data shows up in the database.