The debate about comments is one of the most intense debates for programmers. Even my husband and I have heated arguments as to how to comment the code we work on together. I’d argue that this debate is more intense than the tabs versus spaces one. But, as we all know, there is clearly a correct way to indent your code, there is also clearly a correct way of writing comments. It is much better to write more comments than less. Simply put, may we love, use, and write comments throughout our code.

Because this debate is so controversial, there is a good change that you have heard some very good reasons why not to comment your code (much). Allow me the opportunity to disarm these arguments against comments while presenting my arguments in favor of commenting.

//If you’re a TL;DR person, the last paragraph has the summary

“Good code is self-documenting.”

I hear and read this statement so often, it makes me really wonder what percentage of people are actually writing “good code”. In my personal experience, only about 50% of code is “good code”, and maybe 20% of that is “self-documenting”. Unless it’s your code of course, which I am sure is “good code” at least 90% all of the time.

Now, being honest with yourself, did you CHOOSE to read that piece of code above? Or did you just skip down to this paragraph to get the explanation of the code? The above code says the same thing as the paragraph below,

A question I have is, who is capable of reading code faster than they can read sentences. Or who wants to read code instead of sentences. Even the best self-documenting code will be harder to read than a few phrases written out. We’ve been reading paragraphs long before we were reading code so naturally, we are faster sentence readers than code readers. As they say, time is money, so any time spent slowing a developer down from understanding the code is money lost.

“Comments can lie”

Luckily, annotating code is pretty easy. With tools like `git blame` You know exactly the last author of that line of code, AND the last time the comment updated. It is rather easy, almost too easy, to see who made large changes to a function, and didn’t document the breaking changes in the comment. And that person can be fired or what not.

“I don’t need comments, they get in the way of the code”

Yeah, yeah, yeah. We all know that guy who doesn’t need comments. Or at least claims he doesn’t need them. I understand that when you are in a code base that you know the insides and out, you are able to jump right in and work, picking up the code fast.

This is a major problem. Not because we all know how easy it actually is to forget code you have written and haven’t touched in a while… but because you don’t write comments for yourself. I’m going to say this again, for the people in the back. You add comments to code for others, not yourself. Comments are for the new hires who have no idea what the rest of the code base does, the people who doesn’t know where the puzzle pieces of code fit together in the workflow. You may not be the newcomer now, but at one point you were, and having more rather than less comments would’ve helped you.

Just like ads on the side of our Facebook feeds, our eyes just ignore comments in code. Method comments can be collapsed in most IDEs, and truly don’t get in the way of the code. Ignore them if you don’t need them, but you can read them if you do need them.

Let’s clear up something, I’m not talking about adding a comment for every single line of code. I’m talking about a method function at the top of every function, and occasionally adding a one liner comment inside of a function if something is especially confusing. A small function to state what the function does, any side effects, what the arguments are and the return value is. Bam THAT’S IT. I think we can agree that this is a very reasonable ask.

In summary, comments are easier and faster to read than code. You have been reading sentences and phrases long before you started reading code. Therefore, you can read comments faster than you can read code, even the most “self-documenting” of code. You write comments for others, not yourself. So stop deciding your comment strategy based on your personal preference, be courteous to others and leave meaningful comments. Comments are very easy to ignore, and can be collapsed in IDEs. They don’t get in the way of the expert programmer, but can be the lifeline for the new programmer who needs them.