The “why” of code
A while back, some (way smarter than me) guy named G. K. Chesterton wrote this:
In the matter of reforming things, as distinct from deforming them, there is one plain and simple principle; a principle which will probably be called a paradox. There exists in such a case a certain institution or law; let us say, for the sake of simplicity, a fence or gate erected across a road. The more modern type of reformer goes gaily up to it and says, “I don’t see the use of this; let us clear it away.” To which the more intelligent type of reformer will do well to answer: “If you don’t see the use of it, I certainly won’t let you clear it away. Go away and think. Then, when you can come back and tell me that you do see the use of it, I may allow you to destroy it.”
Now, Chesterton was originally speaking of the Catholic Church. He may not have been so quick to jump to their defence if he had the chance to read the Boston Globe’s excellent journalism on the topic, but his point still stands. In order to effectively remove or change something, you first need to understand why it’s there.
Somnambular development methodology
Somnambular adjective of, relating to, or characterized by actions conducted during sleep
First step in understanding the “why” beind a piece of code is acknowledging that the people who wrote it were not practicing the somnambular development methodology (ie: literally coding in their sleep). It did not spring from the aether fully-formed, in some divine computational intervention. The original developers did not write it just to make your life miserable. They had reasons. Those reasons might no longer be valid, or relevant. Or they might have been wrong and irrelevant from the beginning. But there was a reason. You owe it to your colleagues, the original developers, and to yourself to find out what it was.
Every other developer who worked on this was a moron
- Somebody taking aim at their foot with a shotgun
I’ve been guilty of tearing down fences and insulting the fence builders without stopping to think about the “why”. This is dangerous levels of arrogance. Yes, sometimes I was simply a better developer (though not as often as I’d like to believe). And yes, sometimes there simply was no good reason why a piece of code existed in the codebase – “I copied and pasted it from stackoverflow” is distressingly common. But more often than not, there were actual reasons why a piece of code existed when it seemed to serve no rational purpose.
A cautionary tale
One time, I was working on a piece of code I had inherited from a developer who had moved onto greener pastures before I arrived. The codebase was a mess. I chuckled and reveled in my superiority, secure in the knowledge that had I been the solo dev working on this, it would have been much better.
Then I came across a particularly gnarly piece of code that did… well, I still have no idea WTF it did. It didn’t seem to be referenced anywhere, so I deleted it.
All hell broke loose.
Turns out it was responsible for something. The site no longer loaded. No assets, no database connection, no response other than generic 500 errors. Even
robots.txt would refuse to load.
Feeling “superior” won’t keep production from going down, and won’t make the post-mortem meeting with the CEO any easier.
This is why comments exist
This is what code comments are actually for. Forget the “good code is self-commenting”. That’s simply not true. The “what” of good code can be self-explanatory. The “why”, however, is often impossible to discerne. Yes, I can see that this piece of regex is looking for occurances of the word “dicksissel”, but why does the code care? Help any damn, arrogant fool who might wander by later and be tempted to remove or change what you’ve built by explaining in the code why you wrote it in the first place.
You never know - a year from now, you might looking at some piece of nonsense and cursing the absolute stupidity of whatever moron who wrote this indecipherable… oh shit, is that my name on the git blame?
Steven Allen is a software developer with over ten years of experience.
He's seen many companies fail. Don't be one of them.