The code as a history book

Note: This is an old draft written years ago, that was left unpublished. I released it now as part of desk cleaning. A new version had bee published on medium.

Yesterday I sat with a violin player. He explained that he does not like to listen to the recording, since he enjoys the variations each player is creating while performing live. He is seeking personal expression while performing a well-documented music piece. I think I astonished him when I replied that I identify with every word, seeing the exact same thing while I’m reading code.

Reading code is like reading a history book. You can see the intentions at the beginning. You can see the time something did not work or was not by design. You see where the programmer needed a trick. And unfortunately, you can point out where he got tired or just got lazy. 

Me, here 🙂

As the lead, I’m dedicating time, going over old code. looking for unused sections, repetitive code, or boring easter eggs. Sometimes finding coding horror. On other occasions receive a reminder of some other periods, and other mindsets, noticing how the focus changed within the life of the code and product.

Intro: Evolution VS creationism

The main difference between evolution and creationism is that while creationism state that the current situation is the most ideal that can be, evolution knows that although it works, we just might carry plenty of legacy useless stuff hidden inside. Here is a fun simple code snippet I found:

function doSomething(a, b, c){
    return b + c;
}

The code was much more complicated than that, but the principle is simple: the first argument was never used. Before removing it I looked for all the places that called this function and found exactly four, all exactly the same:

...
doSomething(a);
...

Unless there is a continuous effort on code review and refactoring, reading code is like reading a history book. You can see the intentions at the beginning. You can see the time something did not work or was not by design. You see where the programmer needed a trick. And unfortunately, you can point out where he got tired or just got lazy. More than once I shocked a programmer by describing his intentions and how his mindset changed at each part of the coding process.

Names lie

Giving names is one of the more exhausting tasks, so the developer leaves it for late. Meanwhile, he starts by providing temporary names, just to focus on the ‘fun’ parts and rush to the logic. This is why the naming is the first clue to the programmer’s mindset. On other occasions, it points out that the product had evolved, but the code is still stuck in the past leaving us with exhausting mental mapping.

var postsList = getArticles();

Are we supposed to change only the necessary for the task? keeping a copy-paste process? Or are we required to refactor leftovers? Can it be that the intention of that variable had changed in the middle of the coding process, and therefore we should expect a lot of mess inside the code? Or posts and articles are the same things?

The lie is there! The next time someone will read it, he will treat it as the name claims, and not by its actual meaning.

ASAP

Here is some other code horror:

let c = a.filter((x) => { 
   return x.purchase > i*f*x.items.length;
});
c.foreach((x) => {
   x.discount = i*d;
})

Either it was too simple and obvious for the programmer, or he was so stressed that he felt the need to try something before real coding and then just as it is. In both cases, the code is unreadable and begs for bugs. This is why brilliant programmers are bad for the product. We spend most of our time reading code, not writing it, so KISS!!

Job done

Once more, this a simplified version of the code found inside one of the files…

post.loadComments();
post.loadStatistics();

let user = users.get(post.author.id);
post.author.displayName = user.firstName + ' ' + user.LastName;

display(post);

The programmer has done excellent work of creating beautiful code. But either he got tired or had some annoying leftovers to fill. Instead of taking a meditation break, he added a patch to the code, rushing to announce “job done”.

Found it

function initNewPost(){
   article.post = {
      author : user,
      title: '',
      ...
   }
   article.showNewPostForm = true;
}

I get it, after a long day, or after complicated research, he found the exact spot that creates the bug. The only change needed to solve it is to add one simple line. But with all the respect, even if it’s the safest place, take the time to find the proper place.

Separation of responsibilities

function displayPost(){
   post.showNewCommentForm = post.openForComments();
   post.buttonsList = somewhereStatic.getButtonsList();

   if(post.type == "video"){
      post.buttonsList['edit'] = false;
   } 
   if(post.type == "image"){ 
      post.useHighlighter = false; 
   }

   ...
}

Reading this I know that a programmer sometime later on had to add some new use case for image, without noticing that he violates the rule “separation of responsibilities”. If you have a new type of object with new behavior, don’t just place it inside some unmanageable mess. Handle it with respect and give it its proper structure.

Pure arrogance

This one is the worst, I call it “Hi I learned something new”:

let toogleTab = (…params) => {
    let [a, b, c, d] = […params];
    …
 }

Yes, she was excited to learn that ES6 added spread, she looked for the opportunity to use it. But… Arrrr… Just what the what!!!

Don’t comment it, rewrite it.

The proper use of comments is to compensate for our failure to express ourselves in code. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code.

Clean code. Robert C. Martin

Don’t ToDo it, do it.

Todo is a synonym for “Yes, I know I did a bad work or found something problematic, but still my plan is to leave it for someone else, sometime in the future”. I know, I’m stern, but let us allow the exceptions only as exceptions.

If you need time, say it. Don’t leave a ToDo or comment as a cover for the mess.

Summary:

Code is written by a human, and as so just like any other type of art, it presents its creator. Just as you can hear if the player was trouble while playing the violin, you can read how was the programmer while playing the keyboard.

Me