Not readable, but re-readable

Or how make your code good

Usually, when I hear about quality of the code, I hear the word “readable”. “Make you code readable” they say. And it is good. Most of the times I’ve heard such words, I saw that people means quite simple things:

• Small functions
• Meaningful names of methods/variables/classes/e.t.c
• Consistent uniform code style

And other concise rules. SOLID, YAGNI, KISS. All of that helps you to keep your code clean and readable for other people and for yourself.

But still sometimes I hear a comparison reading a code with reading a book. Just start from some place and keep reading without jumping from function to function. So some of such people don’t like the idea, for example, of small functions? Exactly, because they prevent a calm jump-less reading from top of monitor to the bottom.

I’m not saying of extracting or not extracting duplication code in separate function, I hope everybody understands, that DRY is pretty useful principle; I’m talking about not splitting a function into a small or even tiny parts, since those parts will be used only by our function and thus will be more barrier for good readable code, than a helper. And I disagree with that.

Also, I understand, that most of programmers (at least programmers, that I know) think as I am in a same way. And I agree, that there are tons of situations and variations. And of course, there are circumstances, when you have to write big function. And I don’t want to explain solution for every condition. I just want to discuss the way of think, the approach to writing and reading code.

My code is just like open book.

This is interesting comparison. Indeed. Our code, code of our colleagues in sum is bunch of characters and words, connected to meaningful phrases (sentences), in order to provide some completed (or not) thought. In this angle of problem description, of course the code os some production project is very similar to book of some author.

For some projects it is a drama in three acts. For other projects it is a sci-fi with an unimaginable number of UFcb (Undefined Flying code blocks, that produces unknown results). For some projects it is fantasy full of magic code and spell blocks, that you need to repeat in order to run something. And for other projects it is a horror or comedy.

But I think, that code is not book. More precise, it is not fiction. Thus, I believe, the comparison of reading a code and reading a book takes place be, if we compare code and reference book or programming book. By the way, code is more complex and huge thing and for me it is better to compare it with living creature, you’ve created and taken responsibility for it. So it is your duty to fix it and improve. But I compare only process of reading.

Main big difference between reading some code and reading fiction is your intention. When you read fiction, probably your purpose is to enjoy a good story or get involved in interesting, saturated events, that’s why you need to know every needed (or not, depends on author) details and read your book from start to end.

Other thing happens, when you read code. I suppose, in most cases you don’t want to know whole history, but you need to find something and understand it. That’s why I compared it with reference books or programmings books. Let’s take, for example, Joshua Bloch’s Effective Java. If you go to the beginning of the book, you will see Contents: list of chapters with items and references to pages. This is a peculiar set of functions (chapters) that are call another functions (items). This is done, because, probably you will not read whole book in one run (at least you will do it probably one time), but re-read it over and over again, returning to needed chapters/items, when you will face with issues, problems or you will needed info from them.

My code is different

In real life (at least in my small work experience) huge amount of time programmers spend to reading code. And that’s normal. We need to find broken blocks, we need to exude duplication code in a separate function, we need to find those duplications, we need to find a place, where we place new function, new class or new package.

In all that cases most of time we spend not enjoying some good novel, but to find out, what happening. And for finding it is better to use, as we all remember, trees and maps, not just array or list. That’s why it is important to split your code on small functions. It helps not to read your code, but re-read it. Moreover, it is much easier to making refactoring steps with small functions, not a big one.