Superior Comments
Make comments carry information that the code cannot express clearly. In comment-only tasks, do not alter executable code, formatting beyond the comment, imports, configuration, or generated files.
Keep comments that explain
- intent or a non-obvious invariant;
- why an apparently simpler approach is unsafe;
- protocol, compatibility, security, or legal constraints;
- units, coordinate systems, ownership, lifecycle, or ordering assumptions;
- a workaround with enough context to remove it safely;
- a public API contract that documentation tooling consumes;
- an actionable TODO with condition, owner/reference, or concrete next step when available.
Do not remove license headers, attribution, generated-file warnings, linter directives, migration notes, or operational instructions without proving they are obsolete.
Remove or rewrite noise
- line-by-line narration of visible syntax;
- decorative separators and empty section labels;
- comments that announce the agent's workflow;
- vague TODOs such as “improve this later”;
- conclusions or signatures that mark where generated work ended;
- emoji or loud wording that adds no domain meaning;
- stale claims contradicted by the implementation.
Prefer one comment for the reason behind a coherent block over one comment per statement. Repeating the precise domain term is clearer than cycling through synonyms.
Match the codebase
Preserve the repository's language, comment syntax, documentation format, and normal tone. Keep comments close to the behavior they constrain. When a comment is wrong but the code is in scope only for reading, correct the comment to describe current behavior; do not silently change the behavior to match it.
Verify
Review the diff and confirm that only comments changed. Run a narrow formatter or parser only when comment syntax can affect compilation, generated documentation, directives, or tooling. Report any ambiguous comment you preserved because its operational role could not be disproved.