Wink Pings

Code comments are deceiving your AI

Matt Pocock proposes a method for getting AI to classify and delete code comments: tautologies, excuses, outdated comments, and decision records, then ban them entirely with a lint rule. The comments add a fifth category, 'assertions,' and someone has already built a plugin.

In the age of AI programming, code comments are no longer just for humans. AI agents read them and treat them as facts. Today Matt Pocock threw out a long prompt that goes straight at code comments.

He has AI review every comment in the repo and classify them into four categories:

  • Tautologies: they just restate the code itself
  • Excuses: they make a hack implementation look reasonable, and then spread everywhere
  • Outdated: the referenced code or implementation no longer exists
  • Decision records: they record an important but non-obvious decision

The handling is simple too: delete tautological and outdated comments outright; delete excuse comments and file an issue for that hack implementation; move decision records into ADRs (Architecture Decision Records). Finally, create a lint rule that bans comments, then set up a /delete-comment skill to make repeated cleanup easy in the future. He also had AI estimate how many lines of code could be saved by deleting all comments.

The comments quickly added quite a few details.

Someone added a fifth category: assertions. They describe the runtime behavior of the code and may have been wrong from the very first day they were written. The fix is to convert them into tests first, then delete the comment. One developer caught an example in their own code: a 'holder rolled back, retry' comment, under which the path taken is one real Postgres would never take; running the test exposed it immediately.

Someone has also already turned this into an oxlint plugin. The rule only allows a few special comments: VENDOR (working around bugs in someone else's software), SAFETY (above type assertions), BRIDGE (Effect-to-Promise bridging), and QUARANTINE (skipped tests); everything else is deleted. Tool directives and JSDoc type tags in plain JS files are kept.

There were objections too. ADRs themselves also rot. One developer said it's best to leave a one-line pointer to the ADR in the code; otherwise the next agent won't be able to find it at all. Someone also asked whether public API docstrings should be exempt. Matt made his stance clear in another reply: all comments.

Outdated comments harm AI more than humans. When humans see a comment that doesn't match the code, they verify it. AI directly believes the comment and then keeps building on the wrong foundation. Someone in the comments described it as: comments written by agents poison the context.

One developer posted a screenshot and said they built the same skill today.

Screenshot from Zebro

Another reply recommended a tool called cccc for measuring cognitive complexity and cyclomatic complexity in code. It's written in Rust, is a single binary, and supports nearly twenty languages including TypeScript, Rust, Go, PHP, and Ruby. Running it on the entire zod src — 286 TS files, 68,000 lines — takes only 15 ms with 12.5 MB of memory. By comparison, ESLint plus SonarJS takes 1.8 seconds and 604 MB of memory to produce the same metrics. The recommender uses it to let AI evaluate which tests can be deleted.

Matt's caption for this prompt was: I'm sold. Comments considered harmful.

Two years ago, this line would have been taken as a joke. Now it looks more like an engineering decision.

Code comments won't disappear. But in the era when AI reads code, they have gone from documentation for humans to context fed to models. Writing comments has become something that requires restraint. If you absolutely must write a comment, write it as a test.

发布时间: 2026-11-21 00:33