The Untold Truth of Commenting Code

Photo by Guy Yama on Unsplash

The software engineering debates are plentiful. You might have a discussion about tabs vs. spaces, light mode vs. dark mode and be able to hold your temper. Those particular points of contention are nothing compared to the big one. The one every software engineer has their own philosophy about.

It’s time we uncovered the untold truth of commenting code.

// Comments

We’ve all been there. When you dive into a codebase it’s like going to a new town without your phone — you’re completely lost.

Why would that be there? What is that magic number? Who would structure code like this? Why? WHy? WHY? WHY!

Necessary Comments

This is where comments come in. They provide clarity and guidance where it is needed most, right in your codebase. Comments can illuminate an author’s intentions and explain that difficult code. Not only that, but they can also be useful in explaining the why behind the what to save future developers (including the author) from those feelings of confusion and frustration.

I’m still playing detective looking around code that is years old. The original author has long since left the company and I feel like I’m some kind of code archaeologist. There is no easy way to understand what is going on, and I wish there were just a few comments to give me a clue as to what all this code is supposed to do.

Bad Comments

Alas, not all comments are created equal. Rather than helpful comments describing the why not the what we have this type of code:

Not only do we have the code to maintain, but now we have the comment to maintain too. This is annoying to see in a PR, but even more frustrating when it’s been changed to:

And that’s the type of code I often see in my codebase. It’s the worst as it makes me question my sanity and wonder if there is a simple typo in the code.

A lesser crime is that of the verbose comment:

# This is a function that takes an input string and checks if the string is a palindrome by comparing the string to its reverse.
def is_palindrome(s):
    return s == s[::-1]

If you’re prepared to scroll the code window to read that comment well done you, I found it too boring and just couldn’t get to the end. It’s just too long, boring and redundant. When there is a comment like that, I feel that my intelligence is being insulted.

// The Art Of Commenting

Bad commenting is simply too common and is just too easy to do. Good comments resemble an art rather than a science partly due to the necessity of foresight.

So, here are some coding hygiene guidelines to help you get the balance right.

Don’t State The Obvious

If the code is clear you do not need a comment. Developers can read code, so let them do it.

Update Comments

Ensure comments evolve with your code.

Why Not What

If you’ve implemented a workaround or an unconventional solution you should explain your reasoning.

Be To The Point

Keep comments brief but informative. They should be exactly how long they need to be and no longer. Complex logic might need a comment, but the comment should be less complex than the code to which it accompanies. This paragraph in itself is too long.

Conclusion

To comment, or not to comment. The balance is certainly difficult to reach but get comments wrong and they will be a source of frustration and confusion.

Aim to be the developer whose comments are praised, and whose code makes sense. Be wise in your comments and your future self will thank you.