Become A Better Programmer By Making Your Code More Readable

At the start of my career pushing out as much code as possible was my biggest priority. This meant neglecting the quality of code and just focusing on making the code work - a binary process.

As I progressed from working on small and self-made projects to working in a team for a tech company, I started to put more and more attention on the quality of code I pushed for review.

?? With that, I found that a key component of writing good quality code is its readability. And that’s what we’ll be talking about in this article??

Why Should We Focus On Making Code More Readable?

Referring to the above statement I’ve made - writing code that works is a binary process.

It’s binary because the code either works or does not. It’s like 1s & 0s - you can validate that by a simple unit test of the code piece. ??

Whereas to verify whether a piece of code is readable cannot happen in such of a binary manner.

The problems that come with unreadable code

1. More development time. To put it simply, if an engineer struggles to understand the code and how it flows, it will take him much longer to put out new code and deliver value to the business.
2. Increase in tech debt. Writing unreadable code has a compounding effect, which comes from coders iterating over an ugly piece of code without spending time on making it more readable, because they need to meet quarterly OKRs (for example). Lack of automation testing and CI/CD contribute to this tech debt problem as well.
3. Frustration among engineers. New engineers to the org can get frustrated when they get onboarded onto a team and see code that’s hard to go by. It’s logical to think that the first 3 months of that engineer will be harder, as they struggle to navigate trough the code & always question why things are done in that way and not the other..

Can you think of other problems unreadable code brings? ??

Defining Readable Code

It’s hard to define what readable code is, as the definition varies from person to person & from org to org.

With that said, in his newest book, Gergely Orosz does a pretty good job in defining the two important judges for code readability ??

1. Do you find the code easy to read? Write your code. Go for a walk. Look at your code. Can you follow it easily? Can something be improved? Do you really need this comment and in stead can’t improve the namings?
2. Can others understand it? After the coded passes the above questions, publish it for review. If the code brings misunderstanding to the reviewers - that’s a hint that the readability can be optimized.

Now, I’ve been blessed to have some very thorough reviews, which brought me a lot of self-awareness and made me iterate over my code readability skills fast. With that said, even if you don’t have that environment at your company, ask peers or engineers outside your domain for feedback about your code’s clarity.

The fastest way to grow your skills and career is to always be proactive.

How To Make Your Code More Readable

Now that we know the definition and importance of writing readable code, let’s see how to actually make our code more readable ??

Don’t Repeat Yourself / DRY

Don’t just copy & paste code. Always look for ways to refactor and create reusable components when possible. Avoid brute copy/pasting.

Single Responsibility

First of the SOLID principles, the aim here is for classes to have only one responsibility and functions to do just one thing.

With separated the logic, the code is easier to understand as each core functionality has its own class.

As a result, we 10x our unit testing!

Keep It Simple Stupid / KISS

The simpler, the easier it is to understand. Avoid building large and complex logic in a single class or function.

I’ve worked on code that had multiple thousands of lines per class and it’s an underestimate to say that it was a disaster.. ??

Naming

Mid to large companies have company wide naming conventions in place, so make sure you follow them. More general rules of thumb are:

• Choose names that clearly indicate the purpose or function of the entity. For instance, calculateTotalPrice() is more descriptive than calcPrice().
• Avoid abbreviations as they will confuse someone new to the org.

Commenting

Find out what’s accepted as good or bad practise at your company. Most engineers have strong beliefs in NOT having comments to describe the code, others say they are crucial to the code base.

My opinion is to aim as much as possible for code that doesn’t need comments to be readable. Add comments only when absolutely necessary.

Keep Good Structure

The code base needs a logical structure, because it will help in navigating trough functions, classes and entities.

Moreover, be consistent in the way you define the attributes of a single entity, class or test.. static variables first.. then private ones.. then public..

Iterate On Feedback

Especially for more junior engineers - taking feedback from more experienced engineers and applying it to your code is of huge importance.

Also, new joiners to an org, no matter the level of expertise, should take and apply the feedback on code readability from engineers who have been in the org for a longer period of time. The standards are there to be followed & if someone sees an opportunity to challenge them, they need to do it in a professional and respectful manner.

Working Code > Readable Code

It’s important to note that working code will always have a priority over code readability. I mean, before all — your code needs to work as expected.

The illustration, although funny, is quite realistic! ?? If you have been working in tech for some time, you most definitely came across all 3 personas.. ??

Remember

Coding is a social activity.

Always remember that the code you write in a company will be re-read by future developers.

So look at it like legacy, because in some sense it is.

?? I would love to hear your thoughts on this topic of code readability and whether you can think of any other advice on making our code more readable?

If you want more content like this, follow me @ Konstantin Borimechkov ??, where I post on a weekly basis! Sometimes twice! ??

Also, feel free to check out some of my other articles??