2026-02-11 · Vericode Team · 6 min read
A file full of `// increment i` comments is worse than a quiet file. Readers already know the language. What they cannot recover from the tokens is why the code exists, which inputs are illegal, and which shortcuts were deliberate.
Start with a module or function contract. One or two sentences is enough: who calls this, what must be true on entry, and what the caller can assume on the way out. If a function returns `null` to mean “not found” and throws for I/O errors, write that down. The type system will not always say it.
Comment the non-obvious branch, not the `if`. A timeout that is 280ms because product research found users pause mid-keystroke is worth a line. `if (timer)` is not. The same rule applies to magic numbers, feature flags, and compatibility shims for a vendor bug.
Do not use comments to hide a bad name. If you need a paragraph to explain `proc()`, rename it. Comments are for facts that names cannot hold: protocol quirks, ordering constraints, and “we tried the obvious approach and it failed because…”.
When you add comments with a tool, keep the original structure. Rewriting control flow while “documenting” is a review of a different program. Vericode’s comment action is designed to insert headers and doc lines without renaming symbols or collapsing branches.
A useful habit before a pull request: delete any comment that a junior engineer would call narration. Keep the ones that would save an incident at 2 a.m. That filter is stricter than “add more comments,” and it produces files people actually trust.
Teaching-style comments are for onboarding, not for production forever. If you generate a longer pass for a new teammate, consider a short architecture note in the repo instead of leaving a lecture in every helper. The production file should stay scannable.
Finally, treat outdated comments as defects. A wrong comment is a lie next to executable truth. When you change a constraint, change the sentence that described it. Reviewers should reject stale notes the same way they reject failing tests.
If you generate comments in bulk, run a second pass as a human. Search for words like “obviously” and “simply.” Those usually mark a sentence that should be deleted. Keep numbers, protocol names, and “do not reorder these calls.”