If you’re writing a piece of code that you never intend to read, following coding conventions is a waste of time. Computers, I can guarantee you, don’t care how you cross your t’s and dot your i’s.
In fact, everytime you’re following a coding convention, you’re probably doing more harm than good.
I spend 90% of my time writing code. I spend the other 90% reading the code because I need to add a feature, troubleshoot a problem, or path a bug. I actually read more lines than I write, my estimate is around 5:1.
How productive you are depends on how quickly you can read those lines of code and get what they do, so you can find problems and make changes.
Now, it sounds counter intuitive when I’m telling you not to bother with coding conventions, but that readability of your code is so important. But it all makes sense when you reflect on how we actually write code.
Coding conventions focus on what you write, and following coding conventions quickly turns into a self-serving activity that guarantees your code is readable …. but only the first time you write it.
What happens often, as you’re adding new features, change code and applying fixes, you make a mess. The code was coherent because you thought it will only be written one way, but now it changed so much that it’s no longer following the original narrative.
And if you leave messy code like that, it only becomes worse.
So here’s a different recommendation. Forget about coding convention, just write the code. But when you read the code, follow a simple practice. Fix where you hesitate.
Every time you pause for a few seconds trying to understand a piece of code, you’re dealing with unreadable mess that will only get worse. So fix it, right there and then. Chances are you’ll have to go over it again, so now’s the time to smooth it.
What this leads to is something much more effective than coding conventions. It leads to maintainable code.
First, you learn what readable code looks like, so you know how to write readable code to begin with. And coding conventions don’t even capture the tip of the ice berg. They don’t deal with too many state variables, indecipherable algorithms, or spaghetti flows.
By fixing what’s hard to read, you practice the art of making yourself understood.
Second, as you grow your code, you’re starting to create a mess. This way, you can keep it clean and tidy with routine maintenance. You’ll quickly learn where to fix patchworks so they don’t grow into chaos.
I’m reminded of that after looking at three autrocities I managed to create in only a few hours of coding.
Through some merging of code, I ended up with two functions. One called authenticate and one called authentication. I choose two descriptive names which made sense in the two separate projects from which I copied them. And they’re both clean, flow and well documented.
But for the life of me, I can’t remember which to call when, and ended calling the wrong function in the wrong place.
Through the miracle of rapid iteration, I ended up with a function that works two different ways, depending on the value of its first argument. If you look at the function, it’s clear what it does and why it works that way.
But how come I have a piece of code that calls the same function twice, expecting different results, and what exactly are those two different results?
And the last example is just inconsistency between two different models that provide the same function with two different names. And I can’t remember where to use which one.
So instead of worrying about how I write code — there’s just no way to prevent the mess — I worry about how I read code. What I don’t read, I don’t touch. But when I hesitate, I fix.
Photo by headcase
Chipping the web – 00001111 — Chip’s Quips
Coding conventions are a precondition to readability « AJ’s blog