Comment-verbosity guidance for interactive main-agent coding sessions

[williamthorsen]

Problem

After long interactive coding sessions, the main agent tends to leak the conversation itself — design rationale, paths not taken, defensive justifications addressed to imagined reviewers — into source comments. The result is files where comments outweigh their cost: large diffs, harder reviews, and "code" that has to be maintained alongside the real code.

This problem is not observed (or is far less pronounced) when orchestrated-coder writes code from a plan, suggesting the trigger is conversational accumulation rather than a general comment-style gap. The main agent, having just argued through a design decision with the user, restates that argument in a /** */ block; having explored an edge case in chat, defensively notes "this case is unreachable" in code; having justified a layout choice in conversation, repeats the justification in a JSX comment.

Concrete examples (from a recent session)

• A 25-line file header on a 281-line component, restating what the per-function JSDoc and section comments already say.
• A 15-line file header on a sandbox demo whose default export already carries a one-line JSDoc — making the entire header redundant.
• Inline comments that paraphrase the next line ("Tab to the combobox" above await user.tab()).
• Defensive prose about non-existent edge cases ("The singular '1 option' case is unreachable and is not special-cased").
• The same fact (a maxWidth: 360px constraint and its rationale) documented in two places — a JSX comment at the call site and a JSDoc on the constant.
• Domain coupling in a common/ component: "Defaults to 2 (the planning-grid contract)."
• Re-teaching the underlying library: "Atlaskit Select renders a combobox role…"

Across three files in one commit, comments accounted for ~120 of ~750 lines. A reasonable target after trimming was ~40 lines — a ~65% reduction without losing any signal.

Relevant considerations

• Function/method/class/component descriptions are non-negotiable. Even a one-line description per function is good. The problem is volume beyond that, not the practice itself.
• One-line JSDoc is usually enough. The current guidance ("favor concision, but prioritize communicating the essential information") leaves room for the current behavior.
• The trigger is conversational, not stylistic. Adding more rules to global guidance alone is unlikely to fix it — the agent has the rules; it just stops applying them under conversational pressure to "show its work."
• orchestrated-coder doesn't exhibit the pattern because it works from a written plan with no conversation context to leak. This is a useful contrast — the fix may involve treating interactive coding sessions more like orchestrated ones at the comment-writing step.

Proposed solution

Add a concise set of comment-discipline rules to the global guidance, and reinforce them at a checkpoint the main agent must hit before completing an interactive coding turn.

Rules to add (terse, deletion-oriented)

1. One brief description per function/method/class/component. One line is usually enough. Trivial code (simple getters, one-line helpers fully described by their name) may omit it.
2. Don't paraphrase the next line. If a comment restates the code below it in English, delete the comment.
3. No tutorial-style file headers. A file header earns its place only when it documents non-obvious architecture (composition order, invariants across functions, threading model). It must not duplicate per-function JSDoc. If the default export already has a one-line JSDoc and the file is a single concept, no file header is needed.
4. Don't explain unreachable cases or hypothetical bugs. "X is always ≥ 2 by construction" is reviewer-defensive padding. If an invariant matters, encode it as an assertion or type, not prose.
5. Don't document the library you're using. "Atlaskit Select renders a combobox role" belongs in Atlaskit's docs, not your code.
6. One location per fact. If a constant has JSDoc, its call site doesn't need a comment repeating it.
7. Inline comments answer "why," not "what." "Render the pill in place of the next chip" is what the code does; "react-select types value as a union; narrow to array" is why the cast exists. Keep only the second kind.
8. No process commentary in code. "Centralizes the typing boundary," "Matches the X precedent," "Future readers should note…" — these document the author's reasoning, not the code's behavior. Put them in the PR description or a commit message.
9. No domain leaks in shared/common code. A common/ component's JSDoc shouldn't reference a specific consumer ("the planning-grid contract").
10. Lines of code are lines of code, even when they are comments. They have to be maintained. Every comment must earn its weight.

Mechanism (optional but recommended)

Lightweight self-review step before the agent declares a coding turn complete:

Before finishing a coding turn, scan added/modified comments. For each comment, ask: would a competent reviewer reading the code lose anything if I deleted this? If no, delete it. Pay special attention to comments that restate design discussion from the current session — that material belongs in commit messages or PR descriptions, not in source.

This checkpoint targets the specific failure mode (conversation leakage) rather than relying on the agent to internalize the rules under accumulated context.

Acceptance

• Comment-discipline section added to shared agent guidance.
• A short note added to the interactive-coding flow (or its equivalent) that triggers the self-review step above before turn completion.
• Verified by re-running a comparable interactive coding task and observing that comment density falls into the same range as orchestrated-coder output.

[williamthorsen]

Additional failure modes observed while trimming the example commit

After filing this issue, I (the main agent) applied the proposed trim to the example commit at the user's request. In doing so I committed three further mistakes that the proposed rule set as currently drafted would not have prevented. Worth folding into the same fix.

1. Deleted a function description while ostensibly enforcing "every function gets a description"

When I removed the 25-line file header on MultiSelectWithOverflow.tsx, that header was in form a file header but in function the only description the exported component had. The exported component was left with zero documentation — directly violating the rule the user had stated explicitly at the start of the session.

Proposed amendment: Before deleting any doc-comment block, identify the nearest function / class / component below it. If that target has no description elsewhere, the deletion is not allowed without replacement — the trim must include a one-line (or longer, if salient features and gotchas warrant it) replacement directly above the target.

2. Stripped IDE-meaningful comment syntax without checking what it did

I replaced // region | … // endregion | … markers with plain // --- … --- separators "for consistency." Those markers create named, foldable blocks in JetBrains IDEs (and // #region does the same in VS Code) — they're a navigation affordance, not visual noise.

Proposed amendment: Never strip comment syntax that may carry IDE or tooling semantics — // region/// endregion, // #region/// #endregion, // @ts-expect-error, // eslint-disable-*, //# sourceURL=, /* webpackChunkName: … */, framework-specific directives, etc. — without first confirming what the syntax does. If unsure, ask.

3. Amended a commit not made in this session, without permission

I bundled the trim into the existing HEAD commit via git commit --amend. The user then could not review my changes via their normal review tools because the diff against the previous HEAD was lost. The correct action was a follow-up commit; squashing could happen later, if at all, at the user's direction.

Proposed amendment: Never amend a commit not created in the current session unless the user has explicitly said "amend" for this specific change. The default for any code modification on top of an existing commit is a new commit.

Common root cause

All three are the same failure: the agent applied a generic principle ("less is more," "be consistent," "keep history tidy") to a situation where a more specific consideration should have overridden it. This is exactly the conversational-leakage pattern the original issue describes, just at the editorial level rather than the generative one. The same self-review checkpoint proposed in the issue body would catch all three if it explicitly asks, before any deletion or history rewrite:

• Is there a function/class/component below this comment that would be left without a description?
• Does this comment use IDE/tooling-meaningful syntax I haven't verified?
• Am I about to rewrite a commit I did not create in this session?

If yes to any of these, stop and ask.

[williamthorsen]

Another instance of the same root cause, observed while polishing the same example commit:

A demo's (or page's, or doc page's) text describes the thing being demonstrated, not the demo's own structure.

The original sandbox-demo description for MultiSelectWithOverflow read:

"Exercises MultiSelectWithOverflow across six option-count fixtures. Every panel exposes a slider for maxVisibleChips so the overflow rule can be verified at multiple caps; the last panel additionally exposes a slider for searchThreshold so the soft-cap 'Type to search …' message can be flipped on and off interactively."

Four problems, all the same shape:

1. Inventory rather than description. It enumerates fixtures, panels, and sliders — implementation vocabulary of the demo, not user-visible vocabulary of the component.
2. Duplicates the component's own JSDoc in slightly different wording, so a reader who has already read the component description gets the same content again, less precisely.
3. Buries the lede. A reader who lands on the demo wants to know what the component does first; the demo's structure is self-describing once they know what to look for.
4. Tells the reader what was built, not what they need — the same pattern as the comment-verbosity issue, scaled up to a paragraph.

Replacement:

"A multi-select that keeps its control compact: extra selections collapse into a non-interactive +N pill, and large option lists trigger a 'type to search' prompt instead of rendering every row. Use the sliders to change the chip cap and (in the 250-option panel) the search threshold."

One sentence on what the component does (in user-visible terms), one sentence on how to interact with this demo. About a third the length of the original.

Proposed amendment to the issue's rule set:

Describe the thing, not the inventory. A demo, sandbox, or doc page's prose should describe the subject (what it does, why a reader cares) — not the page's own scaffolding (fixtures, panels, sliders, sections). Implementation vocabulary of the surrounding page is almost always visible from the page itself and doesn't need to be narrated. If two pieces of text describe the same thing (e.g., a component's JSDoc and its demo's intro paragraph), pick the one with the better audience and delete the other.

This generalizes beyond demos: page-level descriptions, route-level help text, README intros, and even commit messages can all fall into the same trap. The agent describes what it built, not what the reader needs.

[williamthorsen]

A further refinement of the "describe the thing, not the inventory" principle, applicable when more than one prose slot describes the same subject on the same surface:

When two prose slots appear on the same surface (registry entry + demo intro, README + module docs, ticket summary + ticket description, page title + page subtitle), each must answer a different question.

Don't write the same content twice with different verbs. The canonical pairing for component-demo surfaces:

• Outer slot (registry description, page header, doc title) → "what is this thing and why would I look at it?"
• Inner slot (demo intro, body copy, page subtitle) → "what do I do here?"

A worked example from the same branch. The debounced-search registry entry uses both slots well:

Registry: "Demonstrates SearchTextbox paired with useDebouncedSearch: typing into the textbox produces a debounced 'effective' value that downstream queries can rely on without firing on every keystroke. A slider adjusts the debounce window at runtime."

Demo intro: "Exercises SearchTextbox + useDebouncedSearch in isolation. Type into the input, sweep the debounce slider, and watch the status panel below."

The first answers what is it?; the second answers what do I do?. The pair is informative.

My first attempt at the multi-select demo failed this rule — the demo intro was a paraphrase of the registry description with slightly different verbs ("Use the sliders…" vs. "Sliders adjust…"). A reader who already read the registry entry got nothing new from the demo intro. The fix was to rewrite the inner slot as imperative how-to-drive-it copy: "Pick a few options, watch how the overflow rule kicks in past the chip cap, and use the sliders to change the cap or — on the 250-option fixture — flip the 'type to search' prompt on and off."

Detection heuristic: if you can swap the contents of two adjacent prose slots without the page becoming noticeably worse, they're doing the same job and one of them needs a different angle (or needs to disappear).

[williamthorsen]

Closing as superseded by #642, which folded in the broader rule taxonomy and orchestrated-vs-interactive diagnostic from this ticket. The combined work shipped in #659.