Comment drafting, code-context analysis and review notes
I got tired of comments that just narrate the code line by line. So I built this. It drafts the kind I actually want to find six months later: the ones that say why a thing is the way it is, or what’ll break if you touch it. Paste a snippet, or just describe what the code does. Pick the language and the comment style. It flags the risky bits, shows you a phrasing or two, and hands back something worth pasting in. Nothing leaves the page, by the way.
Honestly? The best comment is sometimes no comment. Keep yours only when it says something the names or the tests just can’t.
Good code comments explain the reason a reader cannot infer
Nobody tells junior devs this, so I will: a comment that translates code into English is worthless. I can read a loop. So can whoever inherits my mess. What none of us can read is the stuff that isn’t in the file. Why a failure gets left visible on purpose. Why this one timeout gets babied while the rest don’t. Why a config value that looks like a fat-fingered typo is actually load-bearing, or why that ugly workaround has to sit there until the platform team ships their fix. Write that down. The rest is noise.
That’s the whole idea here. It asks the questions I ask myself before writing a comment: why does this even need saying, who reads it later, what facts have to stay true no matter how the code mutates. Then it scans your snippet and flags what usually deserves a note. Network calls. Anything that smells like auth. Stray TODOs, magic numbers, config keys, failure handling. It won’t pretend every comment is a keeper, which I appreciate, because I sure don’t. You get a better first draft. That’s it.
When a comment is worth keeping
My rule of thumb: a comment earns its spot when editing the code without it would ship a bug or punch a hole in security. A docblock spells out what a function expects and how it fails. An inline note guards that one weird branch you’ll forget the reason for by Friday. A review comment flags the bit you want a teammate to eyeball. And a config note? That’s what stops someone copy-pasting your prod values straight into dev and then wondering why everything’s on fire.
- Docblock when a function has intent and caveats worth pinning down up front, before anyone calls it.
- Inline note right next to that small decision that’ll look plain wrong until you explain it.
- Review comment when the next move is a conversation in the PR, not a line in the source.
- Configuration note for the env and feature-flag stuff that bites you the second you change boxes.
- TODO with owner which is worth exactly nothing unless it names who’s coming back to it, and why.
How to avoid comments that rot
Try the boring fixes first. Rename the variable. Split the function. Maybe write a test. Nine times out of ten the need for a comment just evaporates, and honestly I think most comments are a code smell wearing a hat, though I might be talking myself into that. If something genuinely unique is left over, keep it short. Don’t describe the implementation: that’s the exact thing the next refactor changes, and then your comment is quietly lying to people. Pin it to a reason instead. A contract, a limitation, some external system that misbehaves on a full moon, a bug you’re guarding against. And if you can, write down when this comment stops being true, so the next person knows when to kill it.
Practical examples
A few from my own code. A security-header checker needs a comment so nobody later “simplifies” a failed network call into a cheerful green checkmark. A billing webhook needs a note about idempotency, because duplicate events aren’t a bug. They’re Tuesday. A gnarly CSS override earns one line naming the browser quirk it’s papering over. And a SQL filter should explain the business rule behind the condition, not announce that, yes, a WHERE clause exists. I can see the WHERE.
Common questions
Should every function have a docblock?
Nope. A tiny function with a good name and zero surprises does not need a paragraph of ceremony bolted on top. I save docblocks for the ones where the contract or some operational gotcha actually matters to whoever calls them. The rest can speak for themselves.
Are TODO comments bad?
Only the vague ones. A bare “TODO: fix this” is a confession with no plan attached. A good one names who’s on the hook and what has to happen before it can go. That’s the whole difference between a reminder and graffiti.
Can comments replace tests?
Not a chance. A comment tells you what someone meant to do. A test tells you what the code actually does, right now, today. One’s a story. The other’s evidence. The codebases I trust lean on both, because they answer completely different questions.
What makes a good code comment?
It answers “why,” never “what.” The code already covers the what, sitting right there in front of you. What it can’t show is the intent, or the gotcha that’ll bite the next person at 2am. That’s the stuff worth a sentence.
Should every function have a doc comment?
For anything public-facing or genuinely hairy, yes. Callers shouldn’t have to read your implementation just to learn what the params do. But a one-line getter? Leave the poor thing alone. Documenting the obvious only hands people one more line to skim past.
Do comments go stale?
Constantly. And a stale comment is worse than no comment, because it points you the wrong way with total confidence. The only defense I’ve found: keep the comment glued to the code it describes, and edit both in the same commit. You change the line, you change the note. No exceptions.
