Something that we tend to value when learning programming, is commenting our code, explaining what a code block does.

However, the reality is that there are only very few cases when one should add comments, I’ll detail why you shouldn’t write comments, and mention when you should.

• ❗Documentation != Comments
• ⛔ Why you shouldn’t write comments
• ❌ Never, ever, ever leave commented code
• 🩹 Writing code that explains itself
• ✅ When to write comments
• 🔥 // TODO: comments

❗Documentation != Comments

When I mention comments, I’m not referring to documentation, which the latter is always a must.

Suppose you’re writing an API to be used by someone else. In that case, it is a must to leave documentation on it, so the consumer of the API knows what to expect when calling it, and the different developers that implement it also know what to return.

Including code examples in documentation is also great.

There are tools for generating HTML pages of the documented code, examples of those tools include JavaDoc, KDoc, and dartdoc.

⛔ Why you shouldn’t write comments

Comments get easily outdated

We’ve all experienced code with a comment lingering for too long, and when read, it doesn’t make any sense to what it’s commenting.

Code gets refactored very often, comments not so much, they’re commonly overlooked, since one is more focused on writing the feature or fixing the bug, instead of reading a gray-colored comment that isn’t eye-catching.

There’s also another possible reason: one is scared to touch a comment.

Some developers, mainly the more beginner ones, are sometimes scared to even touch an existing piece of code, more so a comment that we’re not certain if it’s crucial.

It’s a sign your code isn’t clear

More often than not, a comment is an excuse for an unclear code.

If your code needs explaining, then it probably needs a refactor. You’ll find some tips later in the post on how to refactor it.

You read both the code and the comment

If the code is clear, the comment is redundant since you’ll read both the code and comment or just the code, begging the question: why is the comment there?

Also, the comment can be distracting, forcing you to read it, even after understanding the code.

❌ Never, ever, ever leave commented code

Commented code gets even worse in terms of sticking there for no reason, and if the code needs to be preserved, that’s the purpose of Git.

🩹 Writing code that explains itself

Here are two simple refactor tips that you can use to make the code explain itself.

Extracting method and variable

Methods are not only to re-use code, they can also be used to make it clearer.

And variables can also be used for that purpose, consider this example:

That substring on line 40 isn’t right away clear that is extracting the username out of the email address.

Now, we could also extract lines 36 and 37, along with the domain comparison, into their own method.

The same applies to the database save, resulting in:

Comparing this to the original method, we can see this one reads like a book.

Before

After

Return early from methods

Instead of chaining if statements like this:

You’d be better off returning early in each non-successful use case.

You can learn more in Refactoring Guru.

✅ When to write comments

We’ve seen when not to write comments, I’ve mentioned there are a few rare cases where it makes sense to do so, these are those cases.

Specific code pasted from somewhere

No, I don’t mean the general “how to send a request” code you’ve pasted from StackOverflow, I mean specific code.

You should link where you got the code from, providing context and possibly updating it if the source is updated.

Take this example from my RustyController project:

It has way more fields below it, that’s why the ignoring of the “unused” rule in line 194.

It’s an algorithm or a mathematical calculation

Similar to the previous one, sometimes algorithms get complex and you can’t immediately identify them, in that case, add a comment mentioning which algorithm it is.

The same goes for mathematical calculations and code that needs to be written that way, for instance, code that interacts with an internal API.

🔥 // TODO: comments

This one tends to get spicy, some like them, some not.

In my experience, TODO comments never get handled, and it’s better to either write a task for them or add to the acceptance criteria of another related one.

Conclusion

To conclude, I just want to mention that comments aren’t to be discarded completely all the time, but before adding one, ask yourself if it’s really necessary, or an excuse to make up for bad code.

In the case of documentation, it’s always a must!