Revisiting a past project


How not to get scared by code you write, a few months down the line

A little while ago I had the chance to work on an old project I set up nearly a year ago. After checking out the code and firing up my editor, I was met with surprise: my code didn't really look the way I remembered it to.

Peeke Kuepers

I think every programmer recognises the feeling: no matter what project you work on, given enough time your code always feels a bit dirty. To put it like Dan Hurvitz:

Looking at code you wrote more than two weeks ago is like looking at code you are seeing for the first time.
Dan Hurvitz

When you're programming, you unconsciously construct a mental model of the program you're writing. It's a bit like the RAM memory in your computer: it allows you to store a limited amount of information for quick reference. This enables you to easily remember how certain pieces of logic work, where functions and variables are referenced and how a specific part of code affects other areas of your codebase.

This mental model also functions just like that invisibility cloak from Harry Potter: it hides the complexity in your code and makes you see past all the weird quirks as if they weren't even there. But sadly there's not enough room in your brain to store all the code you will ever write in this handy quick access register. There will come a moment in time you don't recognize your own code anymore.

Getting reacquainted with your code can be either like catching up with an old friend or an awkward introduction to the new soulmate of your ex-girlfriend. How do we make sure this meetup will be a positive one?

1. Maintainability versus cleverness

One of the beautiful things about programming is that it offers a million ways to reach a solution. It's like solving a giant Sudoku puzzle. Purposefully tweaking your code to work around the limitations of the environment you're currently working in to reach your goal. I'm sure you recognise the feeling of euphoria when you unexpectedly arrived at a solution that works, after trying dozens of possible fixes.

While initially I was really happy with my clever solutions, they gave me a pretty back headache when I returned to this project one year later. Things quickly started to fall apart. What I saw as a clever solution, turned out to also be a rather complex one. Every change to this code caused some unforeseen side-effect somewhere else. The codebase was riddled with these clever solutions, making small changes take way more effort than they should have. 

When you have the choice, always opt for the simpler solution. Designers always set the bar high, but they are reasonable human being you can reason with. Opting for the simpler solution will keep your code futureproof. We must avoid over-engineering our code: rather than solving a design challenge at all costs, we should put our effort in sensible alternatives, simplifying our code as much as possible. Maintaining a healthy balance between cleverness and maintainability helps a lot down the line.

2. Readability versus poetry

Programming has a lot of parallels with poetry. The difference being that programmers do not express feelings, but rather functionality. Like poets however, we all have our very specific views about what beautiful code should look like. 

Give ten programmers a functional specification and every programmer will produce something unique, an expression of their voice as a programmer.
Gil Fewster

It's easy to fall into this trap of programming poetry. And so I did. Using all sorts of obscure techniques to reduce my code to as few lines as possible. Priding myself in the compactness of my code, which was my idea of beauty at the time. 

Where a poem can be beautiful, it can also be difficult to read. If you compare it to a recipe for apple pie, the recipe is definitely a lot easier to understand. It takes you by the hand, guiding you through the process step by step. And if you think about it, there’s a kind of beauty in that too. And if there's any kind of beauty standard you should follow it's that one: readability. Your co-workers will be very grateful!

3. Don’t forget point one and two!

After checking in my changes and riding my bike home, the shame slowly faded away. I remember thinking:

I've learned so much this past year. Obviously I won’t make these mistakes again.
Me a few months ago

Which is — of course — never the case. The biggest pitfall is assuming your code is readable and maintainable, because you can read it right now. But remember Harry's invisibility cloak. This code won’t look the same a few months down the line. Take a step back and squint at your code from a distance. “Is this readable? Maintainable?” Or even better: why not ask that colleague of yours to review your code? 

Liked this article?

Why not follow me on Twitter? @peeke__.