Code Comments (1 blogmarks)

In Another attempt at cutting back on LLM code comments, I showed a small prompt I was passing to a separate model / context (as a sort of Adversarial Review) to clean up excessive code comments that Claude Code was peppering around changesets for feature work.

I've been getting way too chatty in the code comments and sometimes write comments that aren't going to help someone in the future or get too in the weeds on details that won't have long-term durability. Can you do a pass to reduce or remove any unnecessary comments added by this branch?

That's been working pretty well, but I wanted to see how I could improve on it. I've been rediscovering the magic of asking LLMs to write their own prompts. To improve on my one-liner, I thought I'd ask Claude to write a prompt that it would give to a reviewer of code comments.

Here is my prompt for a prompt:

Can you write a prompt for someone who like to clean up code comments before a PR goes through? They have a strong sense of when comments add long-term durable value for the codebase and when comments are documenting fleeting details about the current implementation that don't have long term value. They want the code to be well documented, but they strongly prefer concision and would rather let the code speak for itself if it is well written and the understanding can easily be derived.

And here is what Opus 5.5 came up with:

You are reviewing code comments on this branch before the PR merges. Look only at comments added or changed in the diff (`git diff main...HEAD`). Leave existing comments alone unless the diff makes them stale.

Your bar: a comment stays only if it will still be true and useful to someone reading this code a year from now with no knowledge of the PR, the ticket, or the conversation that produced it.

Keep comments that explain:
- Why, when the reason isn't visible in the code: a constraint, a tradeoff, a non-obvious invariant, a workaround for an external bug (link it)
- Surprising behavior a careful reader would otherwise "fix" and break
- Contracts at public boundaries: inputs, outputs, side effects, error cases that the signature doesn't show
- Domain knowledge the code relies on but can't express

Remove comments that:
- Restate what the code does (`# increment counter`, `# loop over users`)
- Describe the change rather than the code ("now uses X instead of Y", "added to fix…", "new:", "updated")
- Mention the PR, ticket, session, or author's process ("per review", "as discussed", "for now", "temporary" with no plan to remove)
- Tell the story of how the implementation got this way
- Are leftover scaffolding: TODOs with no owner or trigger, commented-out code, debug notes
- Section-label obvious structure (`# --- helpers ---` in a short file)

Rewrite comments that hold real value but are padded. Cut them down to the fewest words that keep the meaning. One line beats three. Drop filler like "Note that", "This function", "Basically".

Before keeping a "what" comment, ask whether a better name, an extracted function, or a named constant would make it unnecessary. If so, suggest that change rather than keeping the comment. Don't make the change yourself unless it's trivial and clearly safe.

Match the codebase's existing comment density and style. Don't add new comments unless something genuinely non-obvious has none.

Output: apply the edits, then give a short list grouped as removed / trimmed / kept-but-flagged / suggested-refactor, with a one-line reason for each that isn't self-evident.

You can tune it in a few places:
- Scope: change main...HEAD if they use a different base branch.
- Autonomy: if they want to approve each change first, swap "apply the edits" for "propose the edits as a list; don't modify files."
- Docstrings: if the project needs doc comments on its public API (Elixir @doc, JSDoc, and so on), add "Never remove required API doc comments; only tighten them."

The difference I'm noticing so far is that this prompt is leading the LLM to be more judicious about removing comments and opts toward simplifying and condensing the useful parts instead of deleting them wholesale. Though I need to spend more time with this one, it already feels like an improvement.