Write Code for Humans, Not for Machines!

Photo by Hitesh Choudhary on Unsplash

Once upon a time, in the land of ones and zeroes, lived code — the invisible threads that power our apps, websites, and software. But there’s a secret about code. It’s not just for computers. It’s for us, humans, too.

The Forgotten Readers

When you type away, creating lines of code, who’s the first reader? A computer, right? Wrong. It’s another human. Maybe it’s your colleague, reviewing your pull request. Perhaps it’s your future self, trying to remember why you wrote that line of code.

Writing for humans means your code tells a story. It has a clear beginning, middle, and end. It’s not a jumble of words (or, in this case, symbols). It’s a tale of problem-solving.

A Tale of Two Codes

Let’s dive into an example using C#. Imagine you’re working on a project where you need to calculate the total price of items in a cart.

Code for Machines:

public decimal tp(List<decimal> p)
{
    decimal t = 0;
    foreach(var i in p)
    {
        t += i;
    }
    return t;
}

Code for Humans:

public decimal CalculateTotalPrice(List<decimal> prices)
{
    decimal totalPrice = 0;

    foreach(var price in prices)
    {
        totalPrice += price;
    }

    return totalPrice;
}

Both will work, but which is easier to understand at a glance?

Code that’s written for humans is often self-commenting. That means, even without additional comments, it’s easy to understand. In our previous example, without any context, “tp” and “t” don’t tell us much. But “CalculateTotalPrice” and “totalPrice”? That’s a story we can follow.

The Long Game

Imagine you scribble a quick note to remind yourself about something. It’s messy, and you think, “It’s okay, it’s just for me.” Now, imagine you have to give that note to a friend in a year. Would they understand it?

That’s the idea with coding. Even if you write something fast today, thinking it’s just temporary, it might stay around for a long time. One day, either you or someone else might need to work on it again.

So, when you write code, think of it like a clear message to your future self or to a friend. By making it clear and simple, you’re making things easier for everyone in the future. It’s like saying, “Don’t worry, I made sure this is easy for you!”

Embrace the Benefits

Have you ever wandered the ancient streets of Carthage in Tunisia? The remnants of this ancient city are a testament to careful planning and craftsmanship. Though it was built thousands of years ago, many parts of the city are still intact and understandable to us. The architects and builders didn’t just build for their time; they built for the future, ensuring that the city’s stories and structures would survive for generations to come.

Similarly, when you write clear and simple code — code made for humans — you’re building something with lasting value, much like the architects of Carthage.

1. Fewer Mistakes: Just as a well-constructed building has fewer structural flaws, clear code has fewer errors. It’s easier to see and fix any mistakes when everything is clear and understandable.
2. Welcoming New Members: Now, imagine inviting someone from a different part of the world to visit Carthage. The well-preserved ruins and clear guides make it easier for them to understand the city’s history and significance. Similarly, when new team members join your coding project, if your code is clear and human-friendly, they’ll find it easier to understand and contribute.
3. Easy Maintenance: Over the years, Carthage required maintenance. Because of its solid foundation, preservation efforts were more straightforward. The same goes for clear code. When you or someone else needs to update or fix it, the process is much smoother because it’s easier to understand.

Summary

Our code isn’t just logic. It’s the manifestation of our thoughts and problem-solving skills. The next time you sit down to code, remember that you’re not just talking to machines, but also to your peers, your future self, and anyone else who may cross paths with your work.