Writing Readable Code: Why It Matters and How to Do It

There's a joke in programming that some code is write-only. It's a reference to the fact that code can be impossible to read, and that the only moment when it can be understood is at the moment of writing.

The reality is that code readability is a big deal with significant consequences.

There are many competing priorities when developing software, and readability can sometimes become a second thought. It's easier to make the case that code should be fast, bug-free, and shipped quickly. But I'm making the case that readability can be a number one priority, too. In fact, it can you help achieve all of the other priorities: it makes it easier to write faster code, it makes bugs more discoverable, and it allows you to ship faster.

Who is it for?

When you're putting effort into making code readable, who are you doing it for?

In some cases, the person who will be reading it is your future self. You might have all the context about the code in your mind right now, and you might think you're going to understand it in the future. But the reality is that we forget quickly.

Making your code readable is a gift to your future self. It's a gift of time and convenience because it will help you get back into the code faster and spend less time trying to figure out what's going on.

Aside from being a gift to your future self, it's also a gift to anyone else who will be reading your code. This includes your co-workers and collaborators who will be reviewing your code in the immediate future. But it also includes people who you don't currently know: future collaborators, or people who will be maintaining your code long after you might be gone from your position or role.

Sometimes you're on a team and you can ask co-workers to explain the code that they wrote. But there are many times when that's not the case: the original authors of the code might be unavailable or they might have left the company or the project long ago. I've had situations where I've wanted to ask the code author for an explanation of what they wrote, only to find out that they're no longer at the company.

Writing readable code is also a gift to those who are learning. What best practices of readability do you want to pass down to future developers? It's a great opportunity: instead of gatekeeping our knowledge, we can make it easier for newcomers into the profession to read and learn.

How to write readable code?

Put yourself into the shoes of someone who is reading the code for the first time and doesn't have a lot of context about how it works. What do they care about?

First, make the intent clear: what is the code intending to do?

The two main tools you have at your disposal for clear intent are descriptive names and intentful comments.

Descriptive names apply to function names and variable names in particular. Here, the idea is to stuff more information about what a function is intended to do into the name itself. Variable names can also have a lot of meaning stuffed into their name: what data they contain, and what that data is for.

The best descriptive names are consistent in their level of detail. And they can evolve. In a simple project, you can survive with short names that don't need to specify a lot of detail. But once the number of functions and variables gets large, then you really start to benefit from longer and more descriptive names. That's because, with growing complexity, there's more to be said about how each name is different from the others.

The second tool is writing intentful comments. This is what I call comments that carry intent. They describe not just what a piece of code is doing, but what it's intending to do. This might mean answering the "why" behind the code. A good "why" explanation doesn't just explain the reasons behind the way that the code was written, but it also mentions the alternative implementations that were considered but were not used.

Intentful comments can be the most useful help when debugging: if you're trying to figure out a bug and you see a discrepancy between how the code functions and how its intent is described, this can be very valuable information for narrowing down the location of the bug.

Writing readable code makes you a better programmer

In conclusion, it's worth making readable code a priority. It pays off in the future, making it easier for you to come back to your old code and quickly get right back into it, and also making it easier for collaborators to work on it.

Writing readable code makes you practice empathy as a programmer. It forces you to think about the state of mind of someone who will be reading the code without all the context and understanding that you have in the moment. And that's a great exercise to make you a better developer.