The Most Important Thing I Learned About Writing Readable Code

One of the most difficult aspects of coding is its readability. Everyone will remember at least one time where they had to go through code that was just extremely difficult to understand. You already have a slight idea of the code’s purpose. But no matter how many times you read through it, you just can’t seem to understand what it’s doing or why it’s implemented in that particular way.

It’s the same thing as a teacher trying to explain something to you. If they’re bad at explaining, it will be very difficult for them to make you understand it no matter how simple of a concept they’re teaching you. On the other hand, if they’re very good at explaining, they will be able to make you understand no matter how difficult of a concept it is.

This also applies to code. Code with bad readability will be difficult to understand no matter how simple the underlying purpose is. On top of that, it can have a lot of long-term consequences. Any activity that relates to interacting with that specific code will become more difficult. Think of reading, understanding, maintaining, and reviewing it.

Even worse, the resulting code can become more prone to bugs and unexpected errors, which can impact the experience of your users.

Being able to write clean and readable code is one of the most important skills of being a good developer. Personally speaking, I’m of the opinion that every developer always has room for improvement in regards to this topic, myself included.

For this reason, I’ve spent most of 2021 taking a serious look into the topic of code readability. The findings and learnings were turned into technical articles. All those articles combined cover a very wide range of processes where code readability plays a role, like writing code, creating pull requests that are easy to review, reviewing other developers’ code, and much more.

During this time, I’ve learned a lot of different things about the topic of code readability. They are also covered by my articles, like how to determine whether code is readable, how code readability affects different development processes, why code readability is so important, why certain code constructions are by default more difficult to read, and the importance of explicitness.

But even so, there was one thing that I never learned during my daily job or while writing all of these articles: communicating it. Knowing about the importance of readable code is one thing, but how do you convince someone to change their code for it? How do you explain that certain constructions are more difficult than others? What if people didn’t agree?

This is something that I faced a lot after writing technical articles about code readability. Whenever I write about the code readability of certain code constructions, there was a high chance of it being a sensitive topic for other developers. Oftentimes, people would comment their opinions about the proclaimed difficulty of certain code constructions.

A few examples of such comments are:

You say that code construction A is very difficult, but I think it’s very easy. [Explanations about A towards me]

I don’t agree. I use code construction B a lot and never had problems understanding it.

Using code construction C instead of yours means you don’t have to worry about X, Y, and Z. They become implicitly given and it makes the code shorter.

While these types of comments seem negative at first sight, they also make sense in a certain way. All of these comments have the same train of thought, namely that they don’t agree that a certain code construction is less readable or more difficult to understand. Their reasoning is that they themselves understand the code construction, so it’s not as bad as I described.

For a long time, I wasn’t quite sure how to reply to these kinds of comments. On one hand, everything they explain about the function is correct and they indeed understand the code construction completely.

Most people assume that I don’t know how certain code constructions work because I’m advocating that it’s less readable, but that’s far from the truth. A recent example is the Array.reduce function in JavaScript. Actually, I almost always prefer the functional array functions on a personal level.

But on the other hand, I still stand behind all the statements that I’ve made in my articles. There are certain code constructions that are less readable or generally more difficult to read. I’ve either experienced this first hand, through other developers or seen it happen with others.

This makes it extremely difficult to reply to people’s comments: I understand their train of thought and I don’t disagree with their opinion, but I also still stand behind my statements. So where’s the problem?

Well, there’s nothing inherently wrong with all of these comments. Everything they’re saying is technically correct, but the problem lies in the way they’re approaching the topic of code readability. In all of these comments, their main consideration is themselves.

They’re thinking: If I understand these code constructions, then I should be able to use them in my code. If I know how these code constructions work, then others will too. If others use these code constructions, then I’ll be able to understand them. This means that the same applies the other way. If I use these code constructions and never had issues, then it should be fine.

The problem is that code readability isn’t about you, it’s about others. You don’t write readable and clean code for your current self. You already know what it should do, what the edge cases are, and where it’s most likely that bugs will occur. You already understand the code.

But other developers don’t know all of this. The developer who’ll review your code, the tester who’ll test your code, the other developer who’ll have to maintain your code or even your future self who’ll work on this code six months from now. All of them also need to read, understand, and work with your code.

It’s for them that you write readable code.

I’m very happy that you understand all the code constructions that I’m writing about to a degree that you can explain them. But not every other developer that will touch your code will necessarily share the same degree of knowledge. However, they are the audience that you’re writing your code for. Making sure that your code is readable for them is part of your job as an engineer. It will make their lives way easier in reading, understanding, and handling your code. Ultimately, this benefits the maintainability of the application as a whole.

After writing technical articles about code readability for almost a year, I’ve learned a lot about the topic of code readability. I’ve learned about its importance, how to determine whether code is readable, how it can affect different development processes, why certain code constructions can be more difficult to understand, the importance of explicitness, and much more.

But the most important thing I’ve learned during this time is that writing clean and readable code isn’t for myself. It’s for all the other developers that will have to read, understand, and interact with my code. Therefore, the most important thing that determines whether a piece of code is readable isn’t my opinion, but the opinion of others.