Julien Jorge's Personal Website

Be precise, be meticulous

Tue Mar 15, 2016

Continuing in the series of behaviors that will make us better developers, today we focus on the importance of being clean, in our code and in our interactions with our coworkers.

Our job as programmers is to write the details of a process in such simple steps that even a robot could execute it. This is the basis without which we cannot even call ourselves “developers”; still it is far from enough to be a good developer. The life of a software expands far beyond its initial implementation, with maintenance, debugging, code review; every line will be read more than once, by more than a single person. That’s why every good book tells us that we should write code primarily for humans.

In an ideal world, not a single developer should have to think about the form when reading an algorithm, nor should we have to find an insinuated meaning behind the identifiers used in the code or the file location. It should be read like a very simple foreign language. Variable names, function names, type names, file names, folder hierarchy, packages, they are all tools we can use to make it clear to our fellow humans why the code is for and how it should be used. On top of these tools come the code style, the form in which we present the code.

I have heard some developers reacting negatively to the constraints of code style conventions by telling that there were tools to do it for them. They had seen some checkboxes and drop down lists in the code formatting section of their IDE and so they thought they could skip the part of formatting their own code because the tool would reorder their functions and could insert some line


, with no



They totally missed the point. They viewed the formatting as a technical step just like the compilation or a preprocessor while it plays a very important role to carry the developer’s intent. Formatting our code is formatting our ideas; it should not be postponed as an intermediate step between the implementation and the submission. Relying on a tool to handle the form is giving up a very expressive way to transmit our intent to the reader.

We know that there is no perfect way to format our code, we also know that there are very bad formatting around. I am not only talking about camel case versus snake case, nor placing the braces on a single line or not; these are preferences we should consent with our coworkers, as a question of punctuation with the sole benefit of making the reviews more fluid. What seems important to me is the visual structure of the code: keeping a consistent indentation, untangling the computations, making visible blocks of instructions related to each other, declaring variables at the last moment in the flow, writing functions for the blocks that appear independent of the surrounding instructions, and so on.

We want our code to be shaped in such a way that the reader could understand the aimed behavior with a simple glance. We want it to look the same if we change our IDE, if our reviewer uses another tool to read it, if it is viewed in Notepad, in Bitbucket’s navigator-limited source view, in GitHub’s one hundred and twenty-five columns, StackOverflow’s eighty columns or in a terminal. We do not want our readers to have to think about the scrollbars when they are focusing on the differences in a two-sided diff view; we do not want them to decipher the indentation because tabs suddenly became fifteen spaces wide, nor do we want them to have to resize their editor’s window infinitely to have a full view of an algorithm.

Each level of expressiveness is done more efficiently when we are meticulous: writing the code in such a way that it makes the computer do the expected task; structuring the program so well that a human can understand it. Being attentive when testing and reviewing the code incurs less bugs and higher quality software.

When I started learning programming, trying different languages and not knowing how computers worked, I would tweak the bounds of my for loops until I could observe the expected result, without understanding what I wanted to compute. My thoughts went like this: should I start from zero? one? And should I stop at the array’s length? minus one? plus one? included or not? I would try every combination until I could observe the expected result. I was approximating at the lowest level, like telling the computer “loop from somewhat the beginning to what looks like the end”.

Approximations in the code produce bugs in the software, approximations in the syntax implies misunderstanding. These are the domains the developers think about but it actually goes far beyond the code. Writing vague stories leads to bad estimations and never-ending validation, being five minutes late at a seven persons meeting incurs a cumulated half hour lost. Doing a stand up meeting while sitting at our desk with a computer in front of us will for sure produce missed informations.

We must be as meticulous in our human interactions than in our code. We must stick to the rules so every one can predict the result of our actions. We do not want to be surprised, surprises require quick understanding and adaptation, which cost time and thus money. If the rules are bad, we have the power to change them, to arrange a new process. But until the change comes, following them is the most efficient way to keep doing a good job. A team cannot work properly if every member follows his own rules.

Thank you for reading. You may want to continue with the next part: keep focus on the feature. If you have missed the previous parts, you can find them there: be a leader, not a hero and be reliable.