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 TODO or FIXME items (unless the user specifically asks to clear them).

Workflow

1. Analyze: Read the target file to understand its purpose.
2. Evaluate: Look at the comments. Run python scripts/comment_density.py <file> (if available) to gauge initial density.
3. 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.
4. 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 today

After (Cleaned):

import datetime

def get_date():
    return datetime.date.today()