How many times will your code be read?

In a successful product, code will be run thousands or even millions of times. Each time an interpreter will read your code (please do not comment on my metaphor). We all know that it’s worth the time to write code that runs efficiently on its machine. Have you ever stopped to ask how many times will a human read my code?

Because I think the answer is a lot.

Most successful code keeps running in a product somewhere long after you might have guessed. There’s 20-year-old code running in at least one of the web sites you visited today. And while your code might well be interpreted by countless contractors, junior devs, and new hires trying to figure out your codebase; there’s one person who’s the most likely person to be rummaging through your code next year, desperate to figure out what it does and why it does what it does.

You.

Always wanted to travel back in time to try fighting a younger version of yourself? Software development is the career for you!

— EIIiot (@Loh) December 12, 2013

Code comments mean leaving yourself a map

And that feels silly, right? Why would you need a map? You built this place! It feels silly. I assure you that you will need this map someday.

A couple of code commenting basics

I should make two points that I often have to cover with beginning programmers.

• Comments do not and cannot impact your code’s performance.

The actual machine that runs your code will completely ignore comments, it’s why we have to mark comments with special characters. Adding a whole novel’s length comment above every function will not slow your code’s execution by a picosecond.

• Long comments are very easy to hide

When you’re starting out with your code editor you might find extremely long comments quite annoying to scroll through to find the code you need to work on. But once you have some experience with your editor you should be able to ‘fold’ comments so they disappear when you don’t need them

A lovely gif of code folding in Visual Studio Code by Bill Souror

If you’re struggling with way too many visible comments, search for a tutorial on how to hide them, or even hide them by default, in your chosen code editor!

Code comments are not code smell

An attitude I see quite a bit is that comments, especially long comments, are ‘code smell.’ Meaning they indicate your code may have problems. I absolutely disagree with this.

The standard example is something like:

var x = user.info3 // this stores the user’s age

And this indicates a problem because it would be better to just name the variable userAge instead of x with a comment. That’s a fair point in this contrived example, but this ignores by far the most common use case for comments. Comments rarely explain only what’s happening in the code comments explain the larger context—the why—of what our code is doing.

While it is possible, though not always convenient, to rewrite your code so that its internal workings are easy to figure out, it is not possible to explain that you’re doing something in an odd or un-intuitive way because of concerns outside of the code.

//this code checks if the account creation date 
//was in 1911 since this (impossible) creation year 
//was used to indicate that these users were  
//imported from the old DB with no creation date set. 

A comment like this one explains code behavior that will never make sense without some kind of documentation!

How to write fewer comments

So, we admit that there are some comments it’s almost impossible to do without. If we really hate writing comments, what’s some way we can do it less?

Probably the most common solution is breaking up functions into smaller functions. A few lines inside the function updateUser might need a comment, but those same three lines inside a separate function named setUserScoreToZero probably needs no comment, this code sets the user’s to zero, ‘nuff said!

Again, this doesn’t get us away from the problem listed above: function names can’t explain external factors. It can also result in longer and longer function names. While code comments are easy to hide, super long function names you’re just kind of stuck with! This certainly doesn’t mean that many small functions, descriptively named, are worse than code comments. It’s just that there are tradeoffs!

But you should be writing more comments

Sorry for the clickbait title, but really, you should be writing more comments, a lot more. Every line? Probably not. Here are the lines you can skip:

• Variable declaration (If you set a good variable name)
• Function declaration (again, good names)

That’s it! Those are the only lines of code you can always skip commenting, everything else might need a comment sometime.

Kindness is key

I won’t link to it here, but a lot of the justifications I see for programming antipatterns amount to ‘if you can’t understand/use this style of code, you shouldn’t be coding at all.’ Whether this is valid or even cogent criticism I’ll leave to one side, only to say that thinking like this is unkind. And when given the choice I will always make design choices that start with kindness.

Every time I take the time to define something I think everyone knows, I tend to get a few thank you comments. Better yet, it just feels better to leave some code comments or write some documentation knowing it might help someone someday—perhaps even the future you. It feels a lot better than tearing my hair out because “no one understands my genius code!”

When we write code comments we are making a promise to our future selves. We don’t know if this code will get reused for decades or languish in obscurity. But if the time comes and these source files are opened again, we will be there. We will offer our help. When we wrote this, here is what we were thinking, we hope it makes sense, we tried to help. Good luck.