When faced with a challenge of cleaning up someone else's code or even our own code (perhaps written so hideously that it makes us distressed), we are often keen to leave most of the code in its present condition and modify only the absolute minimum required. It all starts with leaving the naming as is and not starting 'low enough'. Let me explain why this is a great mistake.
We have all seen them. The is, the js and the ks in the code. Those small, seamingly irrelevant, variable names that slowly, but surely, errode the code in their scope. When cleaning up the code, we will most likely disregard them as an issue, and move on to something of more interest. But that is precisely where the snowball starts to form. If we allow it. Soon we come across a variable named flag , then follows a flag2 or perhaps a fully grown object, conveniently named - sb. Few more lines like this and the code is looking like a cluster of unreadable, mind-boggling puzzles. Programming just became a job.
Although you may be tempted to let some of the minor things like loop counters slide as an i, be warned you are heading towards a slippery slope. And that variable name is not helping you. You should start cleaning up the naming at the very counter variables and propagate your way up to class names, even file names if required.
Why start at the counters and flags?
I would like to refer to a well known theory regarding crime prevention – the broken window theory. For those not familiar with the theory, it states that the landscape communicates to people. A broken window signals the message that the community lacks control and is defenseless against, and vulnerable to - criminal behaviour. The biggest issue is that it displays the lack of cohesiveness of the people within.
The issue might not be that one broken window. Not much harm is done by it. But the arrises when more and more windows get broken, because that one window is left unfixed. Eventually, vandals will start breaking into the building and erroding its internals. Not a lot more time needs to pass before the entire building is in unimaginable shape.
It is very obvious how this theory applies to code as well. The windows are our naming conventions, the buildings are our classes and codebases, and unfortunatelly, if we let it, we become the vandals that keep breaking more and more windows.
How to prevent code erosion?
The only way to truly prevent this is by applying a zero tolerance policy. You can not argue that a descriptive name like wordCount is less readable than i. In an extremely short loop it may seem like unnecessary clutter, but it is not. It is telling us precisely what it is doing and we never need to re-read through the code to understant what it is doing. When thinking of an appropriate name, we should think about how does this name add to the readability of our code.
Does it support the broken windows or the zero tolerance policy?
Ask yourself this question for each and every thing you name, and make no exceptions. Each exception to the rule is an additional broken window on your building. Don't be a code vandal.
Top comments (0)