💬 “Good code documents itself”? Let’s talk about comments

In the programming world, there’s an almost religious debate about code comments. On one side are the “clean code” advocates, who argue that comments are a sign of weakness and insufficiently expressive code. On the other are the pragmatists, who know that without comments, some parts of the code become a minefield.

Let’s figure out who is right and why I am convinced that comments are one of the most underrated tools a developer has.

Myth #1: Good code doesn’t need comments

This is the most popular misconception. Yes, code should be readable. Variable and function names should be descriptive. But code answers the “what” it does, not “why” it does it.

Imagine you see this code:

if (user.level < 5) {
  user.applyDiscount(0);
}

The code is clear: if the user’s level is less than 5, no discount is applied. But why?

Now with a comment:

// Per business requirements, discounts are only available to users
// who have reached level 5 to motivate them to be active.
if (user.level < 5) {
  user.applyDiscount(0);
}

Now everything falls into place. The comment explains the business logic that cannot be expressed through variable names.

Myth #2: Comments quickly become outdated

Yes, that happens. A developer changes the logic but forgets to update the comment. But this is a problem of discipline, not comments.

When you make changes to the code, you update the tests, right? Otherwise, they would fail. Treat comments the same way you treat tests: they are an integral part of the codebase that needs to be kept up to date.

Tip: Make updating comments part of your code review process. See an outdated comment? Ask the author to fix it.

When are comments really necessary?

I’m not suggesting you comment on every line. That creates visual noise and is distracting. But there are situations where comments are invaluable:

1. Explaining business logic

As in the example above. If there is a non-obvious rule in the code that came from managers or analysts, document it.

2. Explaining “hacks” and workarounds

Sometimes we have to write imperfect code. For example, to bypass a bug in an external library or to handle unexpected API behavior.

// Temporary fix: The API sometimes returns 'null' instead of an empty array.
// Awaiting a fix on the backend (Task #12345).
const data = response.data || [];

Such a comment is a lifesaver for the next developer, who won’t spend hours trying to figure out why this strange check is here.

3. Warnings about consequences

If changing a function might break something elsewhere, leave a warning.

// WARNING: This function is used by the analytics module.
// Before making changes, ensure you don't break event tracking.
function calculateTotalPrice(items) {
  // ...
}

4. TODO notes

Leave notes for yourself and the team about what needs to be improved.

// TODO: Refactor. This algorithm is too slow (O(n^2)).
// Needs to be rewritten using a hash map.

JSDoc and other documentation generators

Tools like JSDoc are great. They help generate documentation for your function APIs. But they don’t replace regular comments. JSDoc describes what a function takes and returns, but rarely explains why it works the way it does.

Use them together: JSDoc to describe the function’s contract, and regular comments inside to explain complex logic.

Conclusion: Treat comments as an act of care

Good comments are not a sign of bad code. They are a sign of caring for your colleagues and for your future self. You are leaving breadcrumbs that will help others (and yourself in six months) to understand the problem faster.

So the next time you write non-obvious code, don’t be lazy. Spend 30 seconds and add a comment. Your team will thank you.