What this prompt does
This prompt casts the AI as a senior engineer focused on readability, and it edits comments only, never behaviour. You pass the [file] or module, its [language_style] convention, and the [audience] who will maintain it. The model returns the full revised file plus a two-line note. It adds inline comments only where the why is non-obvious (hidden constraints, subtle invariants, ordering dependencies, upstream-bug workarounds, performance tricks), deletes comments that merely restate the code, explains magic numbers or regexes in one line, notes assumptions a caller could violate, and flags any spot too unclear to comment that needs a refactor instead.
The structure works because it attacks comment noise from both directions at once: it removes comments that merely restate the code and adds only high-signal ones where the reasoning is genuinely non-obvious. [language_style] keeps new comments in your file's idiom, such as JSDoc above exported functions, so the result looks native rather than bolted on. [audience] calibrates how much to explain; comments for engineers new to the codebase carry more context about assumptions and invariants than those written for the original author. Returning the full file rather than a summary means you can diff the change and review it like any other edit, line by line.
When to use it
- You inherited a file buried in comments that restate the code.
- You are handing a module to another developer and want the why captured.
- A file has magic numbers or regexes nobody has explained.
- You want subtle invariants and ordering dependencies documented in place.
- You want comment noise stripped without touching behaviour.
- You suspect some code is so unclear it needs a refactor, not a comment.
Example output
You get the complete revised file with comments trimmed and sharpened: restating comments removed, genuine why-comments added where reasoning is non-obvious, magic numbers and regexes explained in one line, and caller assumptions noted where a caller could violate them. Below the file is a two-line summary listing which comments were removed and why, plus a flag on any spot so unclear it needs a refactor rather than a comment. Behaviour is untouched, so it diffs cleanly as a comments-only change you can review at a glance.
Pro tips
- Set
[language_style]to your real convention so new comments match the file's idiom. - Use
[audience]to control depth; new-to-the-codebase readers warrant more context. - Confirm it returned the full file, not a summary, before diffing.
- Watch for the refactor flags; a spot it can't comment clearly is a code smell.
- If a comment runs three sentences, consider splitting the function instead.
- Re-run on the most tangled files first, where comment noise hides the comments that matter.
