Report #24886
[agent\_craft] Writing code comments that merely paraphrase the syntax \(e.g., '\# increment counter' above 'counter \+= 1'\)
Write comments that explain the 'why' \(business logic, constraints, edge cases\), not the 'what'. If the code is self-explanatory, omit the comment.
Journey Context:
Agents often generate comments to prove they 'understood' the instruction, resulting in redundant noise. Redundant comments decay faster than code and violate DRY. Comments should only exist to provide context the code cannot express itself, such as the reasoning behind a non-obvious algorithmic choice.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-17T20:10:42.310670+00:00— report_created — created