Eli's favorite programming languages are Python and C. He's also proficient in C++, and has various levels of familiarity with Perl, Java, Ruby, Javascript, Common Lisp, Scheme, Ada and a few assembly languages. Eli is a DZone MVB and is not an employee of DZone and has posted 37 posts at DZone. You can read more from them at their website. View Full User Profile

Understanding Your Own Code

  • submit to reddit

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.


Published at DZone with permission of Eli Bendersky, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)



Lund Wolfe replied on Sat, 2013/02/16 - 6:51pm

I totally agree that you are responsible (to your employer, your team now and in the future, and yourself) for taking the time and making the effort to write readable/maintainable code.  I have taken pride myself in code based on tricky algorithms, or very constrained tools or requirements even though it was unreadable/unmaintainable.  It probably could be refactored (and commented) and really only shows that I was at the limit of my intelligence and couldn't finish the job properly.

Sometimes maintainability is compromised due to writing compact code or laziness in refactoring once the code is functional, which is inexcusable.

In the end, writing readable/maintainable code is a skill (independent of language, as you said), and it is unreasonable to expect it from most developers but we should all strive for it.

Martyr Two replied on Sun, 2013/02/17 - 1:58pm

Awesome article! I just wrote a similar article recently titled "Can Tools Make Coding Too Easy? " where I argue a similar point to yours. I was stating that with tools out there beginning to generate a lot of code for us you are seeing this growing generation of programmers who can't even understand their own code because well.... they didn't write half of it. 

I participate on a popular programmer board that sees a lot of programmers asking questions about their code and where their bugs are and how to find them. Often times we see that the tools they are using has created some code and that code some how breaks (or was not right to begin with).

Programmers should know their code and should adopt practices to make sure that not only do they understand their own code, but the code of their tools. You are right on the money. Glad to see there some others out there that believe in maintaining good code practices. :)

Petras Jonaitis replied on Mon, 2013/02/18 - 6:42am

Sometimes you have to fix some issue or add some feature to the existing terrible code. You then debug find out all the hard-coded situations and weird behaviours and add you code which has to deal with it. After few months for me its also hard to remember all those 'stupid' conditions and why I had to write code like this. But I don't consider its my fault since I'm not allowed to easily refactor the core applications code without going through other people approval. So if you are integration your code to other people code (which is pretty much always) its not necessarily your fault that you don't remember why you wrote code in this way.  

ANDRE ROBERGE replied on Mon, 2013/02/18 - 7:32am in response to: Petras Jonaitis

This is what comments were invented for.   If your code has many (in your words) "stupid conditions" that you can't document via code (e.g. assert statements or otherwise), then you should add comments that specify those. 

Todd Runstein replied on Mon, 2013/02/18 - 10:18pm in response to: Petras Jonaitis

Not remembering why you wrote code a certain way isn't the same as writing code you don't understand. If you have to deal with someone else's garbage code, it's your responsibility to do whatever you can to make the additions as clean and readable as possible. I agree, sometimes you have to fix bad code, but that doesn't mean you have to put in your own bad code that you can't understand. Two wrongs don't make a right, and adding unreadable code to unreadable code isn't professional.

Michael Je replied on Fri, 2013/04/05 - 7:49am

 If you have to deal with someone else's garbage code, it's your responsibility to do whatever you can to make the additions as clean and readable as possible. I agree, sometimes you have to fix bad code, but that doesn't mean you have to put in your own bad code that you can't understand. Two wrongs don't make a right, and adding unreadable code to unreadable code isn't professional.

Advertising Here

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.