Hello and welcome back for yet another post on good software engineering principles!

Today, we’ll be talking about readability. What it actually is, how to ensure it, and its (kind-of-obvious) benefits.

What is it?

Readability is how easy it is for another programmer to understand your code when they are reading it. Simple as that.

It is similar to how easy it is for someone to read any other text. You can write a really readable email, a readable tutorial, a readable blog post (like this one :D hehe), you get the idea. Just something that is easy to understand.

We all know (and still love) someone whose written communication makes your eyes bleed and your head spin. You gotta read it over and over just to get the jist of what they want. They may have written it in a rush so there are critical words missing, things are not explained in a logical order, etc.

You can commit similar sins when writing code. But code is inherently more complex than regular text. Even readable code sometimes hurts your head lol, so you gotta be extra careful not to write unreadable code.

Later in the article we’ll go over a couple of concrete ways you can make your code readable, but honestly, it isn’t rocket science. Just read it over and over, and ask yourself if it just kinda makes sense and flows well! This is more an art than a science.

Why is it important?

We’ve talked about the holy grail of software engineering - modularity, low coupling, and high cohesion. Readability dives in a little bit. It tries to look at your code at a textual/line level.

So, you, being the amazing engineer that you are (despite what your boss tells you), have split your system into a bunch of nice cohesive, loosely coupled modules. But the actual code for each module makes you, and any other unfortunate soul that reads it, want to gouge their eyes out.

If you’ll be so kind to recall, the whole point of building a modular system is so that maintenance becomes easier. If the actual code for your modules is simply unreadable, how is anyone going to maintain that? Yes, you still get the benefits of modularity/loose-coupling in that one change request usually leads to touching only one module, but if that module is unreadable, you’re still in a world of pain.

You kinda get what I’m saying? You’ve already spent effort making a modular system, now take it to the next level and make the modules readable!

Ok, I get it. How do I achieve it?

Here are some concrete ways/tips:

  • Use meaningful names - This is the most important thing for readability. Name your projects, folders, files, classes, methods, variables, etc based on what they are.
  • Document public API - Document the public aspects of your code (e.g. public methods in a class). Consider putting a little ‘usage example’ in there.
  • Order matters - The order of things in a file matters. The order of the classes in the file. The order of the methods in a class. Especially the order of the lines in a method. Order encodes meaning. You can use it to make your code more readable.
  • Be consistent - If you use a certain naming style, stick to it. If you use a certain writing style, stick to it. If you use certain idioms/patterns, stick to it! Once someone reads your code for a little, they begin to see patterns, and if you keep consistent, they expect the subsequent things they see. If you all of the sudden surprise them with something different, it just kinda catches them off guard and slows em down.
  • Be simple - Make your logic as short and simple as possible. This may require that you refine it - several times. Often the first time you write something, it is unnecessarily complex (aka convoluted). Each time you refine it, it gets simpler.
  • Group lines - Group related lines together into blocks.
  • Tell a story - Your code should tell a story. Your function is supposed to do something, make the code tell you what it is doing. Names and the order of things really helps with this! This one is also known as ‘self-documenting code’.

Keep these tips in the back of your mind, but honestly just spend some time reading readable code (from well known projects) and you’ll start to build intuition for what it’s supposed to looks like. After that, just read and re-read your own code and try to keep refining it until it just sounds good. Haha I know that is wishy-washy, but like I said, this is an art! Either that or I’m just too lazy to explain.

Conclusion

As usual, here’s a summary!

  • Readability is how easy it is for another programmer to understand your code when they are reading it.
  • You can achieve it by using good names, documenting public APIs, ordering things properly, being consistent, keeping things simple, grouping related lines, and telling a story.
  • However, it is an art. Read a lot of readable code, build intuition, and keep refining your own code until it just sounds good.

That’s all there is to it! Have an awesome day!