chambersxdu/enhance-comment

Overview

This skill removes redundant, obvious, or "AI-flavored" comments from source code to improve signal-to-noise ratio and readability. It targets narrating, translating, tutorial-style, and placeholder comments while preserving useful documentation and rationale. The goal is a cleaner codebase where comments add real value.

How this skill works

The skill scans code for low-value comment patterns—narration of standard constructs, literal translations of code lines, numbered tutorial steps, and empty placeholders—and deletes them. It keeps docstrings, public API docs, warnings, and explanatory "why" comments. After removal it also collapses extra blank lines and trims trailing whitespace for tidy output.

When to use it

• When a reviewer asks to "clean up comments" or "remove AI comments" from a file.
• Before submitting code for review to reduce noise in diffs and focus on substantive changes.
• When refactoring legacy files that contain verbose autogenerated or template comments.
• When preparing a codebase for production where concise documentation is preferred.
• When comments mainly restate code behavior rather than explain design choices or constraints.

Best practices

• Always retain docstrings, JSDoc, or API-level documentation that describes inputs, outputs, and public behavior.
• Keep "why" comments that explain non-obvious decisions, workarounds, or performance trade-offs.
• Preserve actionable TODO/FIXME items unless the user explicitly requests removal of todos.
• Prefer editing overly verbose explanatory comments into concise rationale rather than deleting them.
• Run a linter or formatter after comment cleanup to remove leftover blank lines and normalise style.

Example use cases

• Strip narrator-style comments like "// Loop through the array" from a large JS utility file.
• Clean Python modules that contain step-by-step tutorial comments left by code-generation tools.
• Remove placeholder comments left by templates after the implementation is complete.
• Reduce noise in a pull request by eliminating line-by-line translation comments.
• Prepare a library for release by keeping only meaningful warnings and API docs.