Don't Comment Bad Code — Rewrite It
Over-commenting obscures the real problem: unreadable code. Treating explanatory comments as a design smell forces the harder, higher-value work of simplification and renaming, which pays off every time someone — including an AI agent — reads the code later.
A principle drawn from *The Mythical Man-Month* and hardened by daily practice: comments exist to capture intent and rationale — the "why" — not to narrate what the code is already doing. When a block of logic feels too obscure to stand on its own, the correct fix is to refactor it into self-explanatory form, not to staple a paragraph of prose above it.
The rule has been codified into an AGETNS.md file, treating it as a non-negotiable baseline for AI-assisted and human-authored code alike. If a developer reaches for a comment to clarify mechanics, that reach is itself the bug.
Codifying this as an explicit rule for AI agents is a pragmatic hedge against the verbosity LLMs default to when generating code — they will happily produce a correct but unreadable block and then narrate it in comments, which satisfies neither goal.
The stance treats explanatory comments as a design smell rather than a documentation aid, which shifts the developer's job from annotator to simplifier.