# Comments Considered Harmful > Source: > Published: 2026-09-03 02:33:55+00:00 - Published on # Comments Considered Harmful - Authors - Name - Chris Armstrong Coding agents are very good at generating code comments, pulling together the reasons *why* for a piece of code, what it does, and even piecing together the history of what (it thinks) happened.[1](#user-content-fn-1) But they're not so good at reading or maintaining comments. Agents will happily read comments and assume them into their context, without actually checking if the assertions within them are actually correct. This is not so much a problem when a codebase is still being mapped out for the first time, when the code is fresh and the comments actually reflect the code. But in an actively maintained codebase, code changes downstream may not be reflected in comments upstream, especially if there is more than one module interface between them. Agents are also *sloppy* when making changes. Not only will they update code inconsistently, they'll forget to make changes to comments too, unless actively prompted to check for inconsistencies and resolve them. Combine this with their *propensity to verbosity* and the documentation of minutiae buried within the code they've generated, **allowing agents to generate and update comments should be considered harmful.** At a minimum, your automated code reviewers should be instructed to check code comments for consistency. More than that, you should consider the risks of allowing agents to comment your code at all. They take shortcuts, and trust what is already written, so leaving little nuggets of prose buried within the codebase is just a series of mines waiting to trip up a future agent refactoring the same code. Consider banning comments in your LLM-written codebase altogether, and let your code communicate its intent. If that's a step too far: - limit what your agent is allowed to write about: the "why" in your code only, and references to tickets for fixed bugs in tests - treat code-comment consistency as one of your reviewer gates - have an "end of plan" reviewer that runs through the code after a series of related PRs, looking for comments that add nothing, contradict the code, or are unreadable to humans Footnotes A strong argument can be made *against*their readability to humans, but there's no doubt that they're quick at combining context into a written statement (synthesis).[↩](#user-content-fnref-1)