Coding assistants don't over-comment. They re-derive.

The observation

At 08:45 one morning I ran a prose reduction (comment and docstring) pass over a codebase a coding assistant had written. Across seven files the run took out 210 lines of docstring and comment and put 123 back, a net reduction of 87 lines.

By 19:00 the prose sat 318 lines above where I had left it. One working day of ordinary feature work. The assistant wrote every line and I approved them, diff by diff, because each comment on its own looked like it belonged.

The context

The codebase was three weeks old at 78 commits, roughly 6,500 lines of Python building agents. Most of it came from a requirements document and a corpus of test cases. Comment and docstring lines ran at 25% of the tree on day one and 43% three weeks in, settling near 38%.

Every line was accurate and carried a real measurement. There was a lot of it, arriving in increments small enough to wave through one at a time.

The pattern

One predicate, five lines of code, carried 38 lines of docstring. The same point turned up in four places: the type signature, the failing cases that motivated the predicate, a count across the dataset, and a closing summary. The prose reduction run brought the docstring down to thirteen lines, each fact stated once. Every other instance I opened had the same shape, a conclusion restated.

All four restatements sat in the file as the assistant wrote them, so the context window was already holding every one of them. Each run writes its justification beside the value on its own terms, because for that run the argument is still open.

The obvious gate is a comment-to-code ratio cap, so I measured it before recommending one. Ten hours and those 318 lines later, the ratio had moved from 38.0% to 38.6%. Code grows alongside prose, so the ratio holds steady through the regrowth the cap was meant to catch. A repository-wide lint rule on that ratio stays green all day.

My review missed the growth for the same reason. A single diff shows three accurate lines. Seeing the day takes a total across every commit in it, and I ran that count only because the morning's trim had left me curious.

I tried a flat ceiling first and it failed 111 of 131 files. Pick the number the code ought to hit and most of the tree already sits above it, which leaves two routes. Make the cleanup the project, or ratchet the gate down from today's number. I took the ratchet. A gate that fails almost the whole tree on its first run gets switched off rather than fixed.

How the gate runs

In the build, because that is the only check running at the assistant's cadence. I review when I get round to it. The assistant generates continuously.

Every file gets its own limit, whatever its ratio is today, and from there the number can fall but never rise. Trim a file to 31% and 31% is the new limit. Push it up and the build names the file, printing the old number beside the new. Every file passes the first run by construction. Nobody has to schedule the cleanup, because the only direction the gate allows is downward.

Files over 40 lines now hold docstrings at 20% of non-blank lines and comments at 15%. Two budgets because a docstring is the contract a caller reads and a comment is a note to whoever edits the line under it. One combined budget hides the trade-off. A file can sit well under a single cap while its docstrings swell and its inline notes thin out. The caller loses the contract, the editor loses the note.

The lesson

A coding assistant re-deriving its justification on every run will restate rather than reference. Restating costs it three lines. Finding where the argument already lives costs a search, and that search costs the same however large the window gets.

Pair the gate with somewhere for the argument to live. A decisions file in the repository, one entry per choice, cited from the code by anchor rather than restated beside the value. A run that needs more room than the ceiling allows then has a reference it can point at. The next reader gets one copy of the reasoning instead of four.

Evidence

Every figure here comes from one internal repository, measured after the fact rather than instrumented in advance. The repository is private, so the method below is reproducible against any tree.

• Line counts taken from commit history with git archive <sha> src | tar -x at each commit, then run through a short docstring and comment counter.
• Trim pass: seven files, one commit.
• Ratio walk across 78 commits over three weeks.
• Flat ceiling trial: 111 of 131 files over the bar at the point of switching it on.
• The gate runs in the build, with the ceiling ratcheting down from each file's recorded ratio rather than sitting flat.