“When it was coded, only me and god knows what it means. After two weeks, now only god knows.” - probably all of us at some point in our career

I value readability in code so much when working. I think we should all. It’s not only about ourselves, its about making everyone’s works, collaboration, communication, handovers, maintenances, easier. We need to stop thinking that god-only-know mode when reading a new system is normal. Readable source codes are the best source codes.

Cutting it short, so what’s the trick to check whether a code is relatively readable? Zoom in & Zoom out.

The trick: Zooming the code

Yes, to check whether our code is readable or not, I’ll always advise anyone to try zooming in and zooming out their code. What I meant by zooming is changing the scope which you read it in.

For example, we had this sample code below. If you read it, it’s definitely a find function to count and filter data from Postgre storage:

It’s pretty clear. Yes because this is a short code and I already told you about it. So you know what this code was about.

But when you try to zoom or change the viewing scope, you’ll see some parts that could use some helps. The narrower scope you see it in, you’ll see it ask for higher effort to understand.

Check these out:

Now that probably are some bits that need help. You’ll know it when you have a harder time to read the scoped piece by themselves. This is usually how newcomers (or maybe you in the future) would see them, they don’t get what’s the code about, not like us right now.

Some might say it seems pointless. That code, even if anyone couldn’t understand it, they’ll probably get it in just 1-2min after scrolling up to see the flow from the beginning.

True, very true. But if, we’re taking this to real example, a bigger code, a more complex system with lot of integrated parts, we surely would avoid at all cost, to ‘scroll up and see the flow from the beginning’, right? Sounds like a longer time to accomplish.

Where to go from here?

So, with that trick now you have another trick up on your sleeves to see if something ain’t readable enough. Well, then voila! you will know when you need to improve it. Knowing something is wrong is always 50% job done.

So, how to fix an incomprehensible code? There’s a ton you can do, everyone probably have some sort of style or guideline they follow. For me some of my basic go to approaches are: renaming things, grouping things, adding some annotations (love this), adding some comments, changing the abstractions, recoding the flow, or even deleting the code. I mean, there can’t be a bad code when there’s no code right? Wkwk. Each will require different efforts, choose wisely based on the tradeoffs. 👍🏽

As for the previous code example, we can update it a little bit. It would’t change much because it’s just a short code, but try to compare it with the original code (and try to play with your viewing scope):

Personally, I like this one better. Notice the use of groupings and some annotations, it helps you traverse this piece bit faster.

Addition: How wide/narrow to see?

As an additional note, how wide/narrow the scope to zoom in, will always be relative to your needs.

I won’t necessarily say that you should always zoom in extremely to one-line-scope clarity (checking if each line are understandable by itself) for all of your code. For me, I find it comfortable to ensure comprehensibility over about 15-30 lines. Yes, you can definitely try making it clear in narrower scope, even up to one-line-level-clarity. But excessive zooming would ask for more efforts and could possibly yields an excessively verbose code & comments. Which is usually not needed and it could also hinders maintainability and prone to duplicated texts and so on.

But again, there might be some cases that asks for close to line-level clarities. If it was actually needed, then yeah go for it.

Hasta luego~