Remove "AI-Flavored" Comments
Purpose
This skill guides the removal of low-value comments often generated by AI coding assistants. These comments typically narrate the code structure, state the obvious, or use verbose "tutorial style" explanations that clutter professional codebases.
Identification Guide
Identify and remove comments that fall into these categories:
1. The "Narrator"
Comments that announce the start of a standard coding construct.
- Remove:
// Begin function - Remove:
// Loop through the array - Remove:
// Define variables - Remove:
// Initialize class - Remove:
// End of if statement
2. The "Translator"
Comments that merely translate the code line into English without adding context.
- Remove:
i += 1 // Increment i - Remove:
return result // Return the result - Remove:
print(error) // Print the error
3. The "Step-by-Step" (AI Tutorial Style)
Numbered steps that explain standard logic flows.
- Remove:
// Step 1: Get the data - Remove:
// Step 2: Validation - Remove:
// Step 3: Return response
4. The "Placeholder"
Empty or content-free comments left over from templates.
- Remove:
// TODO: implementation(only if the implementation is already there) - Remove:
/* Your code here */
Retention Rules (When NOT to remove)
Do NOT remove:
- Docstrings/JSDocs: API documentation describing inputs, outputs, and public interfaces.
- "Why" Comments: Explanations of *why* a decision was made (e.g., specific workarounds, optimizations, business logic reasoning).
- Warnings:
WARNING,CAUTION, or notes about side effects. - Todos: Actionable
TODOorFIXMEitems (unless the user specifically asks to clear them).
Workflow
- Analyze: Read the target file to understand its purpose.
- Evaluate: Look at the comments. Run
python scripts/comment_density.py <file>(if available) to gauge initial density. - Process:
- Iterate through comments. - If a comment matches the "Identification Guide" for removal, delete it. - If a comment explains complex logic, *keep it* or *refine it* if it's too verbose.
- Cleanup: Remove any resulting double empty lines or trailing whitespace.
Example
Before (AI Style):
# Import the datetime library
import datetime
# Function to get the current date
def get_date():
# Step 1: Get today's date
today = datetime.date.today()
# Step 2: Return it
return todayAfter (Cleaned):
import datetime
def get_date():
return datetime.date.today()