loading...

Design your code for readability

ice_lenor profile image Elena Originally published at smartpuffin.com ・6 min read

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.

Funny image: what-the-f***/sec as a metric of code quality

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.

Posted on Jun 30 '17 by:

Discussion

markdown guide
 

Great article! I love some of your examples. "...files as big as 40000 lines. Forty thousand".

On your mention of "clever tricks and obscure features", this actually took me back to when I was first learning Python and discovered lambda's and comprehensions. I promptly proceeded to shove as much as I could in a single comprehension, with "fancy" lambdas. It was a nightmare! I really hope whoever saw that code after me quickly got rid of it. And if this person happens to read this...I'm really sorry. :)

On the topic of comments, your examples actually bring up a case where comments are definitely needed, however, what I find interesting, is that, at least for myself I've found when I have to justify using comments it meant my code was not clear enough, so I would review my code and ask:

  1. why am I making this comment?
  2. is there any way I can break the code down further so it does not need a comment?
  3. Instead of a comment, how can my doc string be better (or even introduce one!) to help clarify the functionality of my methods?

However, more so, I would actually depend more on my tests to be the documentation for the code. I'd be interested to know what you think about that? I've found it's helped me structure coherent tests that were well named that helped explain how everything works in the code.

This inadvertently got me to make smaller commits for features that were more relevant to the exact task I was tackling for the given story.

 

Thank you Wajdi, nice to know you like the article!

Love your lambdas example :). I wonder if you tried to read your code some time later? What did you think of it?

40 000 lines is not a joke, unfortunately. :(

Regarding the tests: in my opinion they help a lot to understand the contract. But not the implementation. So sometimes they're not enough. For example, if I'm doing something for legal reasons, or if it's complex business logic, or it's a workaround, I always write a comment explaining that.
With only a test you can see the result, but don't know why it should be like this.

A docstring is sort of a comment as well, isn't it? Of course, it's also very helpful.

Ultimately, I try to look at the code as if I see it for the first time, and explain it to myself with comments.

 

Really enjoyed this post!
Wholeheartedly agree about your stance on comments, they are just as important as the code.

It also made me think of a quote from a programming book I read in college, Structure and Interpretation of Computer Programs by Harold Abelson

“Programs must be written for people to read, and only incidentally for machines to execute.”

If I'm ever a team lead I'm going to drive that point home in every code review and have my team members read this post.

 

Thank you, Andy! Absolutely agree on machines. Happy you liked the post!

 

Good article. Always something we have to be concerned about. I took it upon myself to configure a linter for new projects at work. At least, the repository will have the same syntax everywhere. Rules can be changed or added later. Not perfect, but it feels like only one person wrote the whole thing.

Now, on to all the other reminders :)

 

Thanks, Damien! For my previous project we had a linter too - helped a lot. Also the team climate has improved. No one was arguing about whether to put spaces after brackets when calling a method or not. The productivity has increased)). Only positive consequences. So yes, great advice!

 

Really good article highlighting if the basics things are done right, it really helps in long run and helps you keep your code clean.

 
 

Very helpful article,Thanks.

 

Thank you, glad you liked it!

 

Thanks for breaking down this very good reminder.

 

Thank you, Jess! Nice to see your comment.