This article was originally published in my blog smartpuffin.com.

So, how do you usually code?

You have a task: add this thing to that place. First thing you do - you find where "that place" is and how to get "this thing". To do it, you read the code.
Reading happens every time you need to do something, doesn't it? If something doesn't work, or you need to optimize it, or add one more tiny thing, you search for the place in the code and read it again. And again.

Developers read the code much more often than write [1]. Even if you're writing a completely new thing from scratch, you still return to relatively "older" parts of the code to modify them. While in the beginning you remember everything about your code, after some time you start to forget. You start to read more and more before modifying a piece of code. Then another developer comes to help you, or to do their own thing, and they also read your code.

In a big company, thousands of developers will read your code and modify it over time.

””””””
This is why writing readable code is sooo immensely important. I can't stress it enough.

Personally, I think it's the first thing young developers should be taught. It seems kind of obvious, but in practice not everyone takes care to write readable code.

"Readability" is a very wide concept. Let me list just a couple of things I include there myself.

Avoiding clever tricks and obscure features

You've just read in a Perl book that a function will return the result of the last statement, if an explicit return statement is missing.

Brilliant!

It saves you time typing the return and thus increases your velocity. You can use it every time now!

And you write this.

sub do_something_important {
  # ... some code here
  if ($condition) {
    @array = some_function(@array);
  } else {
     another_function(@array);
  }
}

Now, your new colleague is reading this code. They have 10 years of experience working with Java and C++, but not so much with Perl. They might well think this function doesn't return anything, right? In Java you have to return the value explicitly. Or even if they know Perl returns the last value, they'll think that if no one cared to actually type the return, it's not important, and the return value is not assigned anywhere.

So, your colleague adds a statement in the end of the function. And suddenly the page stops loading.
Your colleague spends some time debugging and googling, but eventually understands what's the problem.
Hmm, thinks the colleague, I'll just add a return after my statement. But what should I return?
The body of if is pretty clear, it returns @array. But what is being returned in the else block? They go to another_function, but it also doesn't have any return statement in it... Can it be a number? A string? Is it @array or some other array?

Not typing the return has saved you twenty seconds. But how much more time will your colleague spend?

Spoiler: I've been this unfortunate colleague, and I spent quite a lot.

I have more examples that just blow my mind when trying to read them.

unless (a1 && b1) {
  if (!a2 || b2) {
     # ...
  }
}

Or this one. It's just black Perl magic, isn't it?

$hash_ref->{"some_name_$hash_ref->{some_other_name}"} = 1;

Using constants

if (value == 605 || value == 606 || value == 8000) {
  // ...
}

What do these numbers mean? What makes them so special among all other integer numbers in the world, all the way from -2147483648 to 2147483647 and beyond?

Why only those three? If I add a new item to the main list, should I add it to that list?

If I should have, but I didn't stumble by pure chance upon this list, how am I supposed to find it?

Of course, the problem with this code goes even deeper. If I didn't add a new number in there, does it mean we display inconsistent information in our application? Do we harm customer's experience?

Meaningful naming

Names should be descriptive. They shouldn't be shortened for the sake of less typing. Again, you read more than you write, so in the end you'll save time making them readable. ProcessWordMatrix is better than Run. SetEmptyToFullRatio is better than SetRatio.

Writing useful comments

This goes along with the naming. A name can be only so long, but it's very important to explain to the reader why you wrote that piece of code.

Some people make arguments that comments become irrelevant quickly, so it's better not to have them. But you should treat comments as part of the code, they must be as up-to-date and as good as the code itself. Comments must help the reader and not confuse them. If you change the code, don't forger to change the comment!

Comments are not for saying "sorry, I know this piece of code is bad". They are for saying "we should display this message because of legal reasons", or "this is the base class for font".

Short functions, small modules

In my experience I saw files as big as 40000 lines. Forty thousand. I think I'll refrain from pasting examples in here :).

40000 lines is approximately the length of The Lord Of The Rings book. You can't possibly read and understand a piece of code of this length. After all, you're just a human.

Dividing the code into short pieces helps you to navigate through the code, to understand what each and every part of the module does, and to easily add new things.

An obvious advice: every function should have a clear purpose reflected in the name. You should be able to scroll quickly to see the name and the description. And by that I mean: no 2000-line functions. My tunnel syndrome doesn't allow me to scroll that long.

Same goes for every module, class, package, any other code unit.

Cleaning up unused code

There's this function in the code that seems to do something useful. It's been called, calculates something, and the result is assigned to a variable. But the variable is never used. Or is it? Does this function have some side effects you don't know about, and thus must be called? Or did someone just forget about it, and now it's like the Flying Dutchman, haunts the endless waters of code without purpose? People spend time to read it, occasionally to modify and support it, but it's already dead inside.

Sad story, I know.

Conclusion

What will happen if you don't care whether your code is readable? Well, the obvious short-term problem is that someone will spend a bit more time reading your code. Seems like not a big deal, right? But if they don't understand your code completely, because it's vague and tricky, they might implement their feature with a bug. They might break your code. They will waste a whole evening debugging. And then some time later someone else will waste another evening. And then someone will waste a morning, and their whole day will be ruined.

All this is especially important in a big company. It has people with various experience, like 10 years in Java, or 20 years in C++, or straight from the university with no previous coding experience. We need them to onboard fast, to start coding right away and to bring value. And, of course, before changing the code, they need to read it. If the code is not readable enough, they will spend much, much more time adding a new feature, than if it were more readable. And for the company, this means money.

Next time, when you're done coding, but before you push it: just stop for a moment and look at your code. Put yourself into another person's shoes. Is it readable? Can a junior developer understand it? Will you be able to understand it in a year? If not, then make it better and try again!
Of course, this will take you some time. But it will take much more time for other developers to read it afterwards. You're borrowing it from them. And it's not fair. ”””””” ””

[1] "The ratio of time spent reading versus writing is well over 10 to 1", says Robert C. Martin in the Clean Code book. I tend to agree, while I don't have precise numbers.

This article was originally published in my blog smartpuffin.com.