Understanding Your Own Code
I recently ran into a statement that left me very perplexed. A programmer was proudly declaring that he can’t understand every piece of code he wrote a week ago. I honestly tried to figure out where the pride comes from, but I can’t. Is he proud that he writes so much code every day? That anyone is willing to pay him to write code?
Let me state my opinion on this matter clearly up-front: not being able to understand the code you wrote a week ago, or a year ago, is unforgivable for a professional programmer.
There, I said it. And now allow me to elaborate. I’ve been programming seriously for around 15 years now. At some point relatively early I adopted some programming practices that have been with me ever since. I can still easily understand code I’ve written a year ago, two years ago or twelve years ago. Code in various programming languages, covering various domains. Algorithms, parsers, web apps, embedded controllers, scripts, linkers, you name it. Even if I look at earlier code, while it’s more difficult for me to understand, I can recognize that some patterns already started to emerge.
The main practice enabling this is realizing that code must be readable. Readable by you, readable by others. Code that isn’t readable is as bad as, or worse than code that doesn’t work. And if you can’t understand your own code after some time, there’s no chance someone else will be able to understand it, ever. That’s not a product of your effort to be proud of.
I can’t stress enough how important it is to be able to read and understand your own code easily. Not only because it makes it a generally better product, maintainable by others. Also because your code is your personal toolbox, one you will use and reuse over and over during your career. Having such a toolbox is extremely empowering, and is one of the most distinguishing features of experienced programmers. I can’t count how many times my problems were immediately resolved by recalling that I faced something similar in the past, digging through my own code archives and finding a solution, or something resembling it. Obviously, code you don’t understand can’t take part in such a toolbox.
It would be unfair to finish this post without at least trying to explain how this feat can be achieved. Frankly, it’s not easy to put in words, but I can try.
I’m pretty sure it’s a trick also used by writers (and probably practitioners of every other creative profession). Once you’ve written some piece of code (the smaller the better), you have to stop and figure out if it’s readable and understandable. Read and re-read it, several times. Try to detach from your current stateful understanding of the problem, imagining someone who is reading this code without all the useful context you currently have in your head because you’re writing it. Would such a person understand it? If not, why not? Don’t hesitate to use every trick in the “code readability” toolbox taught by books like Code Complete, until you’re confident that the code is understandable.
And once you’re happy with the result, read it again. And again after a couple of days. This reminds me of writing the deeper technical articles for this blog; for each sentence I write, I read 20 and rewrite 5. Often this is also true of the code I write. Perfection can be achieved either by a gift in your genes, or by ruthless practice and iteration. Since I was not possessed with the former, I stick by the latter.
Finally. refactor and improve fearlessly. If you run into a piece of code that could be clearer, make it clearer. Improving code quality is one of the subtle side-tasks of our profession. It’s one whose benefit is sometimes difficult to quantify, but after you’re involved in one or two multi-year multi-person mega-projects, you just understand subconsciously.