A bit of a pet peeve I have is code that is just written to "impress", but what it just does is confuse the person trying to understand what the code does. Believe it or not, this person is most of the time yourself, but a month later.

So, have your future self thank you and let's learn what it takes to write readable code. It's really not that hard. Let's get started.

Making code readable

If you can understand what a piece of code does with just a glance, you got it. If you have to ask yourself, is this readable? you don't got it.

Some simple ideas you can implement:

Descriptive variable names

Make sure identifiers are descriptive enough so that you immediately understand what they are and do.

I am sure you agree with me that

calculateTotalPrice(itemPrice, quantity, discountPercentage);

Is much better than if we used

cTP(iP, q, dP);

On a similar note, you should hint in a variable name what kind of type it is. Especially in languages where you don't need to specify types. A boolean should be isOpen or hasItem and not open or item

Format your code the same way as the rest of the file

If you work alone you won't run into this problem as much since you probably have developed your own programming style.

But if you're working in a team you should make sure your code looks the same as the rest of the file/project, this makes it for everyone much easier to understand what's going on. If code is suddenly formatted differently, you have to do some context switching in your brain, this could throw you out of your train of thought.

Use the proper amount of comments

I am sure you have seen this one around plenty of times. Use comments! But it's not just that you need to use comments, it's that you need to use the appropriate amount of comments.

This is a useless comment:

// Check if the number is negative
if (number < 0) {
    ...some other code here
}

Good comments explain complex pieces of code that are not immediately clear. Which will still happen sometimes.

But the best comments are for when you (for example) experience a weird edge case bug in production and you need to implement an extra if statement in which it's not obvious why you added this piece of code.

The benefits of readable code

Okay, so now that we've looked at some simple examples of what makes for good code, let's see why we should write good code.

Maintainability

This is probably the biggest reason. Code that's easy to read is easy to maintain and improve upon. What a waste of time it is to spend 2 hours trying to figure out how a piece of code works before you're able to implement a new feature or fix a bug that would've only taken you 15 minutes otherwise.

Cooperation

If you're working in a team, it's important that the team works together well. When everyone in your team writes readable code it doesn't matter who's working on what part of the system. They understand what's going on.

Luckily, in a lot of bigger teams, there are guidelines for how they write code in their company. And you might not even get your pull requests accepted if you fail to follow them.

Growing your company

You might be working alone or for a small company right now. But eventually, you might hire someone or your company will grow. These new developers need to get up to speed as fast as possible, clean and readable code helps with that a lot.

If the new guy understands your code and can provide value right away, you've done a good job.

The exceptions

And I can hear you say, "But Mr Linxed, in the real world it isn't as easy as you make it sound like here in this article", and you're right. Let's look at some exceptions.

Performance

If you're working on a critical piece of software you might need to put performance over anything else. And that's all right because let's face it, readable and clean code is not always the fastest code out there.

But most of the time, the differences are so small that you'll never notice that you've used an extra variable in your code.

If you're worried about the bundle size of your code because of the larger file size due to longer variable names and more code. Utilize minifiers in your build process. They'll probably do a better job at minifying your code than you'd be able to do manually.

Legacy code

I am sorry to hear that you're working with legacy code. Especially if it's badly maintained and not written in a clean and readable way. But here is the thing, you don't have to fix it. But you should always make sure that what you add or edit is up to standards.

Here is some wisdom I try to apply to all the areas in my life: Leave a place a bit better than you found it.

This can also apply to your legacy code base.

Other tips on increasing the readability of your code

Of course, you don't always want to manually fix all the issues in your code.

Automate it

This is the obvious one. There are plenty of tools out there that will automatically fix some of the formatting. Remember that these won't (not yet at least) rename your variables or add useful comments, that's still your job.

Code reviews

As mentioned quickly earlier, conduct code reviews regularly and make sure the code (aside from checking if it doesn't contain malicious code or obvious bugs) is also following the correct practices when it comes to readability.

If you're working alone, you might want to consider making pull requests for yourself and checking your code a day or two later with a fresh pair of eyes.

I hope this article has taught you something new, or at least put you back on the right track if you were off it.

Writing clean and readable code will be helpful for you and everyone around you in the long run.

Your future self and your boss will thank you.

That's it for now, have a lovely day!

If you're looking to get more done check out my other article

Accomplish more with the "Cult of Done"

Mr. Linxed ・ Feb 18

#productivity #beginners #discuss #motivation

Or if you're looking for a way to host your site for free, check out my article on that

Host your web app for free on Cloudflare Pages

Mr. Linxed ・ Feb 9

#webdev #tutorial #beginners #frontend