Recently I’ve encountered something incredibly amazing and at the same time straighforward and explicit. I was doing my job (yeah, it is) - writing software. And after completing assigned tasks the chief made a code review of my work of art.

It was as always. Like, I was advised to put this piece of code into function, make a variable of another type here, modify a logic of code a bit in that place to better suit the requirements, etc. The code I was working on was challenging, requiring deep and meticulous logic, numerous function calls and accurate flow conditions. And we get to the moment when my entire world transformed from ‘before’ to ‘after’.

To the untrained eye, it was hard to grasp the idea of code without any help from the person who wrote it (me), despite the comments I added here and there. The chief said that it was pretty screwed up because he could not comprehend even half of it without my explanations. It was a mess.

So he showed the code he had written for a similar task/problem to provide me with a correct example of how to do it right. And I was stunned by the “magnitude of readability” that had been put into the code. I could easily understand what the code was doing without the need for excessive comments (in code) and notes from the chief. Naming of variables and functions was appropriate, some pieces of code were placed into separate functions to make it easier for any programmer to use and understand it. There were no raw logic/computations in the main functions, making it even easier to follow the code’s logic.

It was beautiful! I could read it like a book: line by line where eventually they form a meaningful page, chapter, and the whole book itself. And then I understood that my code should be the same. At least, I should always aim to write software this way.

To conclude, I would quote one famous statement: “Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability”.