Here is a scenario every developer knows: you open a file you wrote eighteen months ago, stare at a perfectly functional block of code, and have absolutely no idea why you wrote it that way. The logic runs fine. The tests pass. But the reasoning, the context, the three hours of debugging that led to that one weird conditional, is completely gone. You are now a stranger to your own work.

That feeling of lost context is not just frustrating, it is expensive. Studies from the software consultancy SoftEdge estimate that developers spend roughly 58% of their time reading and understanding existing code rather than writing new code. When that existing code has no comments, that percentage climbs fast. Comments are not documentation for the computer. They are documentation for the humans, including your future self.

The Code Tells You What. Comments Tell You Why.

This is the core distinction that most developers miss early in their careers. Code is inherently self-describing at the mechanical level. A function called calculateTax() obviously calculates tax. You do not need a comment that says // this calculates tax. That kind of comment is noise.

What the code cannot tell you is why the tax calculation rounds down instead of up, why you excluded a specific edge case, or why you chose this algorithm over the faster one you also considered. That is where comments earn their keep.

Consider a real-world example. Here is a comment pulled from a well-maintained open-source financial library:

// Do NOT use Math.round() here. The IRS requires truncation, not rounding,
// for quarterly estimates. Using round() will cause off-by-one cent errors
// that compound across thousands of records. See IRC Section 6654.

If you removed that comment, the code would still work. But the next developer who touches it, maybe someone trying to “clean up” the calculation, would almost certainly introduce a compliance bug. The comment is not explaining the code. It is protecting a decision that took research to arrive at.

The Three Types of Comments That Actually Matter

Not all comments are equal. Once you understand the three categories worth writing, you will stop wasting time on the ones that add clutter and start writing the ones that genuinely help.

1. Decision comments. These explain why a choice was made, especially when the obvious choice was rejected. Anytime you find yourself thinking “I tried X but had to use Y because…”, write that down. It takes thirty seconds and saves hours.

2. Context comments. These tie the code to external reality: a business rule, a legal requirement, a third-party API quirk, or a bug in a dependency you had to work around. Code can only reflect internal logic. External context lives nowhere else.

3. Warning comments. These flag danger zones. Something that looks like it could be simplified but cannot be, a section with known edge cases, or a function that must be called in a specific order. Senior developers who write code for long-term durability are especially good at this. They have been burned enough times to know what future developers will try to “fix.”

The types of comments you can skip: restating what the code already says clearly, commented-out dead code left “just in case” (that is what version control is for), and jokes that made sense at 2am during a release sprint.

Why AI Makes This More Urgent, Not Less

There is a tempting argument that AI coding assistants are making comments obsolete. If an AI can read your code and explain it back to you, why bother writing the explanation yourself? This argument sounds reasonable and it is wrong.

AI tools are extraordinarily good at describing what code does mechanically. They are much weaker at recovering the intent behind a decision, especially when that intent involved constraints the AI has no access to: a conversation with a product manager, a legal requirement from a compliance team, a performance benchmark you ran last year that ruled out three other approaches.

There is also a deeper issue. AI models can behave unexpectedly when operating on incomplete context, and a codebase without comments is a codebase full of invisible context that the model simply does not have. When you ask an AI to refactor or extend undocumented code, you are asking it to make decisions without the reasoning that led to the original decisions. That is a reliable way to introduce subtle bugs.

Comments are the bridge between human intent and machine execution. They become more important as the machines get more capable, not less.

A Simple Framework You Can Start Using Today

You do not need to retrofit comments onto your entire codebase at once. Here is a practical approach that fits into your existing workflow:

The “future stranger” rule. Before you close any file, ask yourself: if someone who has never spoken to me opens this in a year, what would they most likely misunderstand? Write one comment that addresses that. Just one.

Comment at decision time, not review time. The moment you make a non-obvious choice is the moment the reasoning is most vivid. Write the comment immediately. Waiting until a code review means reconstructing your reasoning from memory, which is both harder and less accurate.

Use TODO comments with teeth. A TODO that just says // TODO: fix this later is useless. A TODO that says // TODO: replace with streaming parser once the CSV files exceed 500MB, currently batch processing is fine is actually informative. Include the condition that would trigger the change.

Treat comment debt like technical debt. Ignoring the unglamorous maintenance work has compounding costs, and uncommented code is a classic form of technical debt that looks invisible until someone spends two days untangling a system they should have understood in two hours.

The Real Cost of Silent Code

The software industry has spent decades optimizing how fast code gets written. It has spent considerably less effort on how quickly code gets understood. That asymmetry is expensive at the individual level, and catastrophic at the organizational level when key developers leave and take the institutional knowledge with them.

Your code is not just instructions for a computer. It is communication with every developer who will ever work in that system, including the version of you that exists six months from now with different priorities and hazier memories. Write for that audience.

The comment is not overhead. The comment is the work.