Tired of endless AI comments in your code too? Meet commentdiet

AI agents generate too many comments. And instructions do little to help. So, to keep comments from turning into literary works, I built a linter that works with a pre-commit hook to prevent commits with too many comments. After finishing their work, agents start optimizing their comments without any extra prompt.

First, I looked for existing solutions, but there was a catch: they measure the ratio by line count. When I tried counting lines, the agents quickly started writing everything on a single line. To put it mildly, that did not help.

The linter turned out to be pretty simple. We calculate the ratio of comment characters to code characters and check it against the limits. There are three limits:

• Per file: 20% by default
• Per directory: 15%
• For the entire project: 10%

That might sound like a lot of comments. But it is not: comments tend to be quite verbose compared to code. And 10% does not amount to many comments across a project.

Of course, these limits can be changed. There is also an option to ignore small files.

What this looks like in real code

To get an idea of what limits to set, I measured what I had at hand:

Clearly, for public projects, especially libraries, you’ll probably want higher limits. Almost all the private projects I cannot name here were already within the 10% limit.

The linter supports C++ and Go because those are the languages I use. Adding other languages would be straightforward if there is demand.

Obviously, the linter does not assess comment quality, and it may push agents to optimize comments too aggressively. Still, they manage and provide feedback when something is wrong.

How to run it

From the project root:

docker run --rm -v "$PWD:/src:ro" serguacom/commentdiet:latest

The image is based on scratch and contains a single static binary. It is just over a megabyte and is available for amd64 and arm64. The project is mounted read-only; the linter writes nothing and makes no network requests. Exit code 0 means the check passed, 1 means too many comments, and 2 means a configuration or execution error.

Pre-commit hook in .git/hooks/pre-commit:

#!/bin/sh
docker run --rm -v "$(git rev-parse --show-toplevel):/src:ro" serguacom/commentdiet:latest || exit $?

Or, without Docker:

go install github.com/serguacom/commentdiet@latest

Code: github.com/serguacom/commentdiet

Another nice bonus is that the linter runs at the end of the task and does not add to the context load, unlike a prompt asking for concise comments. It enters the context once the main work is done, when the most demanding part of the work is already done and top-tier, error-free performance is no longer required. A prompt, on the other hand, lowers the agent's IQ a little right from the start.

I do not know how everyone else runs their agents, but mine run in a sandbox and cannot modify the hook. I recommend doing the same.