Thoughts by Bruno Bernardino

Write code for humans, not machines

How some recent coding trends are focused on the wrong things

December, 2014

iMac

NOTE: While I’m talking about JavaScript, this idea applies to any language.


A recent trend of making code “pretty” and smaller has been hitting the scene.

It’s focused on making indentation smaller, variable names shorter (tmp, I’m looking at you), basically, removing “unnecessary” bits (like semicolons).

It’s focused on the wrong things.


Humans vs Computers

Humans are reading your code.

Computers parse it, and won’t have a problem understanding it if a variable name is longer or more descriptive. Trust me.

Humans will.

How can you potentially start fixing that? As an example, instead of calling a callback function callback (or worse, cb), try afterProductsAreFetched or even productsCallback.

You won’t run into weird callback6 scenarios or _____callback. Your self in 6 months will appreciate what you did right now, looking at that code then.

Look at code you wrote 6 months ago

Most developers I know (myself included at times) don’t remember why a certain method or function is doing what it’s doing. They don’t remember why it was done that way, but they’re certain it was working properly then.

When you look at code you wrote 6 months ago, it looks like foreign code. “What’s k?” you will ask. Well, you should’ve written car or product. You wouldn’t be asking that question if you did.

Comment everything. Really.

Code I write gets looked at many different people at many different times. I’m proud people usually don’t have any problem understanding what’s happening and why it’s happening. That happens not only because I write very descriptive code (yes, some variables and functions sometimes get a big long, but trust me, what you will “gain” by shaving those two or three words is not worth the minutes or hours you’ll need to understand that function again in the future), but also because I comment everything.

All functions, all ifs, “blocks” of logic, they’re commented. Even simple things that seem obvious like writing a comment saying “Loop through every person to fetch their open github issues” before a line of code like:

async.eachSeries( people, function loopPeople( person, personCallback ) {},);

Will make wonders when you’re reading that code in the future. While you have context now (while writing the code), you most likely won’t have it then, reading it. With those comments, you get people to understand what’s happening while reading the code, not have to really “go through it” to understand what’s happening.

It’s a huge time saver.

Suggestions

While I take pride on the code I write, I’m learning and making changes “every day”. I’m not claiming my code is perfect, but I see how people seldom struggle with it (including myself when I look at it after a year or so), so I believe I’m doing something right.

If you have any suggestions on how to write better human-readable code, I’d love to hear those.


Bruno Bernardino

Written by Bruno Bernardino.
Thoughts can change, disappear, or simply be observed.

Go back to all thoughts.