Is your code actually readable?
3 simple criteria for readable code
Clean code is a very widely discussed topic. Whole books have been written about it (and very good ones too!). But it’s also a topic, that at times, is overrated and reduces developers from productivity. Being aware of writing readable code is very important and in no way a waste of time. However, doubting the code you produced permanently will lead to decreased output and lower your self esteem. Your business will thank you, if that’s not the case, so here are three simple criteria with which you can define readable code:
Can your co-workers read it?
This one might seem straightforward, but it’s often forgotten. The reason why we write high quality code in the first place, is so our co-workers can read and extend it. This question can also be adapted to fit more detailed cases, for example if you are trying to figure out if a comment is needed: Will this comment benefit my co-workers? Don’t be afraid to simply ask. Code reviews on pull requests are a very important thing. But you can share your code way before that and pull a co-worker to you for some quick feedback. This is also a very efficient way to spread the know-how to Junior developers. For instance, if you answer this question with no, because there are missing fundamentals, you can supply links and perhaps an introduction on the topic.
Can you read it?
Can you actually read your own code? This is a very underrated question to ask yourself, immediately after writing code. If even you cannot read your code, chances are no one else can! This question will also stop you from copying code you don’t understand, just because it works (e.g from StackOverflow). Say you find the function below on StackOverflow, and it works like a charm, but can you read the code?
Chances are it’s a little bit unclear what the function does, even to yourself. Adding a comment with an example input/output already makes it way clearer. In addition to that you could use good variable names, such as objectToGroupBy instead of xs and perhaps entry instead of x. Some further small refactoring and the code is readable, at the very least, by yourself.
Will you and your co-workers be able to read it in 6 months?
Now obviously you cannot time travel to figure this out, but take a second to envision this. Imagine not touching the repository for six months. All of a sudden there is a new, small requirement. Be truthful with yourself: will you struggle to touch the code base? You probably will, but if you are confident that you will still be able to read the code then, without being directly involved in the project, that’s a very good sign.
And that’s it, if you can answer these questions with a yes and a good conscience, you are good to go!
One thing to understand is that reading code is inherently harder than writing code. This is why we tend to label code as unreadable, or even bad, quite quickly. When writing code we break down a problem into smaller problems. This way we can solve big problems extremely efficiently and without keeping the big picture in our mind at all times. But when reading code, especially in a repository unknown to us, this can be quite challenging. Your code can be clean, but not easy to read, these two are not mutually exclusive. Thanks for reading!