Write Code for People, Not Computers

When I first started programming, I had an obsession. I wanted to use as few lines of code as possible and still have a working application. So I’d come up with all kinds of hacks to combine logic into a single line. That’s what makes a good programmer, right? Creating working code in as few lines as possible, right? Right?

Wrong.

Going back and looking at code I wrote from just a few years ago makes me cringe, and this is one of the reasons why. My code that was written with a preference for the fewest lines possible is confusing. I had to have comments everywhere, since it wasn’t obvious what I was trying to do. Even with the comments, I often have to read through that old code several times just to see what’s going on. Not a good place to be.

Nowadays, I try to write code for people, not computers. While I do feel that comments are necessary and valuable, when I write code for people, I need fewer of those comments. Program logic seems to flow better, there’s fewer bugs, it’s easier to test, and I more easily remember what’s going on when I have to go back and look at it down the road. But how exactly can you go about writing code for people? I’m glad you asked.

Use Names That Are Self Explanatory

Your computer doesn’t care what you name that variable or function. It’ll happily use them no matter what, as long as you don’t use a reserved word for one of your names. But I’m here to tell you that you need to take the time to be as descriptive as possible with those names.

Take variables, for instance. You might, out of your need for speed, just give variable names like x, y, z and the like. But it makes your code hard to read. Which is easier? This:

if t > m r = true else n = true end

or this:

if taxes > one_million you_are_rich = true else not_as_rich = true end

It’s obvious which is more readable. Of course, you can say that you know what x, y and z stand for, and I believe you. But will you still remember when you come back to this a year later? Or will another dev who comes along know what you’re trying to do? Probably not.

Method names are something else to consider. How many times have you come across something like MyClass.process() or MyCoolObject.calculate()? These aren’t self-explanatory, which makes them problematic. They could mean almost anything. Renaming those as MyClass.add_to_order() or MyCoolObject.calculate_price would help a lot.

Be Careful With Boolean Parameters

It took me a while to understand why this can be an issue, but it’s often a problem. Remember that with classic object-oriented programming, you should be able to look at an object as a ‘black box’. In other words, you only have to know what methods to call on the object, not about the inner workings of those methods.

But boolean parameters work against this premise. Take a look at this example of how you’d have to call a method that’s written this way:

Order.calculate_price(true)

What’s true here? Is this referring to the ability to use a negative price? To the exchange rate? Something else? You can’t tell because the boolean isn’t very descriptive. It gets even worse with multiple parameters. I’ve written this kind of monstrosity before:

Order.do_something(true, true, false)

Ugh. This code is unclean. Don’t touch it. Instead, use a descriptive parameter. If your language supports hashes or something similar, give them a try. You can do something like this in Ruby:

Order.calculate_price(use_exchange_rate: true)

Much clearer. You no longer need to guess or look up what that parameter or the function is actually doing.

Think Twice Before Doing Something Cute

We all write clever code. Sometimes, it’s too clever. I know you’ve been there: you write something that is concise and works nice, yet isn’t exactly clear. Because it’s so concise, and maybe because it’s a bit unique, you begin to get emotionally attached to it. But chances are high that you need to rewrite it to be more readable.

Though hardly unique, the ternary operator is a frequent culprit. In the old days, when I was try to conserve lines of code, I loved the ternary operator. It was so concise. I could say in one line what previously took five! Amazing! But I hardly ever use it anymore. It requires too much thought to figure out what’s going on when I come back and read it later. So the next time you’re tempted to write:

somethings_true ? do_this : do_that

Don’t. Try this instead:

if somethings_true do_this else do_that end

Much nicer, no?

Writing Code for People Saves Brain Cells

Specifically, it saves your brain cells. But also those of whoever might be reading your code next. So focus on making things readable rather than on being concise. Of course, concise code is often elegant code, but don’t sacrifice readability of the sake of conciseness. Other programmers, including your future self, will thank you.

Source: