People Code

In our day to day, we sometimes get carried away with writing a set of instructions for the machine to execute, in other words – programming. But when you stop to think about it a little bit – machines don’t care about how we write the code – they only care about the instructions provided.

So who are we writing code for? The human, or the machine? Both. But sometimes we forget the human part.

And I don’t blame you. We all do it.

It’s s easy to get carried away by that shiny feature we’re working on. It’s going to do all these amazing things it’ll be wonderful. So we keep the goal in mind and eventually become consumed by the goal and forget to stop and think what we’re doing.

Tell a story

Storytelling is everywhere – writing, marketing, business, sales pitches, photography, and yes – also your code.

Your code tells a story of how the program is supposed to work.

To better illustrate this, have a look at this interview puzzle code that I found on GitHub.

Have a look and see if you can figure out what the code does exactly:

const mysteryFunction = function (v) {
    let remaining = v - ~~v,
        str    = '' + ~~v,
        len    = str.length,
        pos    = 0;
  
    while (--len) {
      pos += 1;
      if (pos % 3 === 0) {
        str = str.substr(0, len) + ',' + str.substr(len);
      }
    }
  
    return str + remaining.toFixed(2).slice(1);
  };

How long does it take for you to figure out what the function is doing?

Did you search what double tilde character does? Did you find a StackOverflow thread?

Now let’s see if we could write the same function in a way that tells a story of what’s going on, or in other words, is self-documented:

const mysteryFunction = function (rawAmount) {
    let amount = rawAmount.toFixed(2).toString()

    // Start traversing the string at position before the trailing decimal chars (.00)
    let currentCharPosition = amount.length - 3

    while( currentCharPosition >= 4 ) {
        currentCharPosition = currentCharPosition - 3
        amount = amount.substring(0, currentCharPosition) + ',' + amount.substring(currentCharPosition)
    }

    return amount
};

Readability test

To see how well these perform in our head, let’s try describing these two functions into sentences.

Mystery function takes a value and uses that to compute remaining, string and length values. The initial position is set to zero and the string is set to be a rounded number using a double negative bitwise not operation.

It will loop until the length value reaches zero, decrementing the length value on each iteration and increment position value.

In each iteration it will check whether the position cleanly divides by 3 and if it does it will then insert a comma at the position of the current length iteration position (not to be confused with position).

Finally, it will return the produced string combined with remaining value and convert it to a float.

I don’t know about you, but that doesn’t read that well to me. Let’s go on and try writing down the second mystery function:

Mystery function takes in a raw amount and ensure that the amount is represented as a float in a string.

It sets the first character position to ignore the trailing decimal characters and starts traversing the string.

It will loop while the current character position is greater or equal to 4.

In each iteration, it will move the current character position 3 positions to the left. It will then insert a comma at that position.

Finally it will then return the produced string.

Even though some of the complexity is still there, the second example is overall easier to understand.

Machine Code vs People Code

Code for the machine is focused on giving the machine instructions to perform the desired action. It doesn’t really matter on how you do it, as long as the machine is able to understand you. Bonus points for using the most optimized language features that will make the code fast.

Code for the human is focused on telling the person reading the code on what is the desired action, while also instructing the machine.

In other words:

Machine code is a set of instructions for the computer.

People code is a descriptive set of computer instructions.

Writing code for people is difficult, because you now have to communicate with the machine in a way that’s also clear to a human at the same time.

This is also where the “don’t write code comments” idea comes from. If your code is human-readable – you don’t need to write comments to explain what the code does, because the code is already self-explanatory.

Suggestions

When writing code, get into the habit to pause for a second and just think about these few questions:

  • Is there a better way to do this?
  • How would I explain this to a beginner?
  • Will I understand what this does in 2 months ?
  • Am I using language features that are easy to understand?

And remember – you’re writing computer instructions in a way that’s easy to understand for people.

Leave a Comment

Your email address will not be published. Required fields are marked *