I was staring at a screen at 3:14 AM, trying to figure out why a legacy payment service was dropping every tenth transaction, when I found it: a comment that simply said `// logic for handling edge cases`. That wasn’t a comment; it was a lie. It told me absolutely nothing about the specific, fragile race condition that was currently melting our database. Most people treat documentation like a chore or a compliance checkbox, but if you want to know how to write a comment that earns its place, you have to stop treating code like a textbook and start treating it like a crime scene investigation.
I’m not here to teach you the “correct” academic way to document a function or how to follow some arbitrary style guide. I’ve spent fifteen years breaking things in production, and I’ve learned that the only comments worth the disk space are the ones that explain the why behind the weirdness. I’m going to show you how to write notes that actually save your future self from a mental breakdown, focusing on the trade-offs and the “gotchas” that the compiler is too polite to mention.
Table of Contents
The High Cost of Avoiding Redundant Comments
We’ve all been there: staring at a block of code that looks perfectly logical on the surface, only to realize it’s a minefield of implicit assumptions. The problem is that when we try to avoid redundant comments by leaning entirely on “self-documenting code,” we often end up with something that is technically readable but contextually hollow. You can name a variable `retryCount`, but that doesn’t tell me why we’re using an exponential backoff instead of a simple loop, or why we specifically chose three retries before failing hard.
The real cost isn’t just the extra lines in the PR; it’s the cognitive load imposed on whoever has to fix this when the service starts throwing 500s. When we skip explaining the why in code, we are essentially forcing the next engineer to perform a forensic investigation just to understand a single logic gate. I’ve spent far too many hours tracing back through git blames just to find the original intent of a “clever” one-liner.
Ultimately, the goal of writing clean code comments isn’t to narrate the syntax—the compiler already knows what the syntax is doing. The goal is to capture the context that the code itself cannot express. If a comment doesn’t provide a piece of information that is impossible to derive from the code alone, it’s just noise that will eventually rot and lie to you.
Why Meaningful Code Documentation Saves Your Sanity
I’ve spent enough time staring at a screen at 3:00 AM, trying to decipher why a specific conditional branch exists, to know that the debate of commenting vs self-documenting code is often a distraction. You can write the cleanest, most elegant functions in the world, but elegance doesn’t explain why you had to bypass a standard library function to avoid a race condition that only appears under heavy load. When I’m debugging a legacy service, I don’t need a comment that tells me `i++` increments a variable; I need the context that explains the weird edge case we encountered during the last Black Friday surge.
Ultimately, explaining the why in code is an act of empathy for your future self. We like to pretend we’ll remember the nuances of a specific architectural compromise, but memory is a leaky abstraction. If I spend ten minutes writing a concise note about a non-obvious workaround, I am essentially buying back an hour of my life for the next time this system breaks. It isn’t about following a handbook of best practices; it’s about reducing the cognitive load required to keep the lights on when things inevitably go sideways.
Five rules for comments that don't suck
- Document the “Why,” not the “What.” I can look at a `for` loop and tell you it’s iterating over an array; I can’t tell you why we’re skipping every third element to avoid a race condition in the legacy payment gateway. Tell me the intent, not the syntax.
- Explain the trade-offs you made. If you chose a slightly slower algorithm because it’s easier to reason about during an on-call rotation, write that down. It prevents the next engineer from “optimizing” it into a disaster because they didn’t understand the context.
- Warn about the “Landmines.” If a specific block of code only works because of a weird quirk in a third-party API or a specific database configuration, flag it. A comment that says “Do not touch this without checking the connection pool settings” is worth more than a thousand lines of clean code.
- Keep them close to the reality. If you’re writing a comment about a function, put it where the function lives. Don’t make me hunt through a separate `docs/` folder to find out why a specific edge case is being handled in the middle of a service layer.
- Delete them when they become lies. There is nothing more dangerous than a comment that describes how the code used to work three versions ago. If you refactor the logic, you are legally obligated (in my book) to update or kill the comment. A wrong comment is worse than no comment at all.
The Rule of Thumb for My Future Self
If the comment explains what the code is doing (e.g., `i++ // increment i`), delete it immediately; if it explains why we chose this specific, non-obvious approach to avoid a race condition, keep it.
Treat comments as a way to document the “dead ends”—the logic we didn’t use because it caused a memory leak in staging—so the next person doesn’t waste three days rediscovering the same mistake.
Aim for high signal, low noise; a single sentence explaining a weird edge case is worth more than a paragraph of polite filler that obscures the actual logic.
The Bottom Line
At the end of the day, effective commenting isn’t about following a style guide or satisfying a linter; it’s about reducing cognitive load for the person who has to fix this when everything is on fire. We’ve talked about why redundant comments are just noise that obscures the actual logic, and why the “why” is infinitely more valuable than the “what.” If your comment just restates the function name, delete it. If it explains the specific, weird edge case that caused a database deadlock last Tuesday, keep it. Your goal is to provide the context that the code itself cannot express—the intent and the trade-offs that led to your specific implementation.
I still keep a notebook of these little lessons, mostly because I know my future self is going to be tired, caffeinated, and prone to making the same mistakes. Writing good comments is an act of empathy for your future self and your teammates. It’s a way of saying, “I’ve been in this hole before, and here is how you get out.” Don’t aim for perfection or exhaustive documentation; aim for clarity under pressure. If you write comments that actually earn their place, you aren’t just documenting code—you’re building a safety net for the next person standing in the trenches.
Frequently Asked Questions
How do I know when a piece of logic is "obvious" enough to skip a comment versus when it’s actually a hidden trap?
If the code describes the what, it’s probably obvious. If it describes the how, it’s likely self-explanatory. You skip the comment when the logic follows the natural flow of the domain.
Is there a middle ground between writing nothing and writing a paragraph that no one will read in six months?
There is, and it’s usually just a single sentence about the “why” instead of the “how.” If the code tells me what is happening, the comment should tell me what the developer was thinking when they chose this specific, weird approach. I call it the “contextual anchor.” Don’t explain the syntax; explain the edge case or the weird business rule that makes this logic necessary. If it doesn’t explain a decision, it’s just noise.
How much should I focus on documenting the "why" versus the "how" when the implementation is particularly non-standard?
If the implementation is non-standard, the “how” is usually obvious once you’re looking at the code, but the “why” is a mystery. I don’t care that you used a bitwise operation instead of a standard library function; I care that the library function has a memory leak in our specific kernel version. Focus 90% of your energy on the rationale. Explain the constraints that forced you into this weird corner. The “how” is the code; the “why” is the context.
At what point does a comment become technical debt itself, especially when the code inevitably changes?
A comment becomes technical debt the moment it starts describing what the code is doing rather than why. If you change a logic gate and forget to update the comment, you’ve just planted a landmine for the next person. I treat comments like a high-interest loan: they provide immediate clarity, but if they aren’t maintained alongside the implementation, the “interest” paid in confusion during a midnight outage is massive. If the code explains the how, the comment should only exist to explain the intent.
