awesome-code-cleanup
Code Cleanup
Audit and clean every code comment in a repository (or a scoped part of it) so the code follows: comments only when strictly necessary; the code itself is authoritative and self-documenting; kept comments are 1–2 lines where possible. The pass is strictly behavior-preserving — a comment pass that changes behavior is a failed pass.
Every comment gets one of four verdicts:
| Verdict | When | Action |
|---|---|---|
| DELETE | Restates code, narrates flow, tutorial-style, echoes a signature | Remove |
| CONDENSE | Load-bearing but bloated | Compress to 1–2 lines, keep the essence |
| FIX | Stale, misplaced, or contradicts the code | Verify against code, rewrite accurately (or delete) |
| KEEP | Dense gotcha/contract that genuinely needs its length | Leave intact, flag in report |
The FIX class is the highest-value work. Redundant comments are noise; stale comments are lies. A real pass regularly finds comments claiming constants that changed ("10,000 rows" over VOLUME = 2_000), explanations of mechanisms that no longer exist, JSDoc stranded above the wrong function, and references to deleted files. Always verify a suspicious comment against the actual code before rewording it — and never "fix" a comment to say something you haven't confirmed.