comment-generator

name	comment-generator
description	Generate code comments and docstrings. Use when user asks to "add comments", "document this code", "explain with comments", or "add docstrings".
allowed-tools	["Read","Edit"]

Comment Generator Skill

Automatically generates clear, helpful comments for code.

When to Use

This skill activates when the user wants to add comments to their code:

• "Add comments to this function"
• "Document this code"
• "Add docstrings to my Python class"
• "Explain this with inline comments"

Instructions

Step 1: Identify Language

Determine the programming language from:

• File extension
• Syntax patterns
• User specification

Step 2: Choose Comment Style

JavaScript/TypeScript:

/**
 * Calculates the sum of two numbers
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} The sum
 */
function add(a, b) {
  return a + b;
}

Python:

def add(a, b):
    """
    Calculates the sum of two numbers.

    Args:
        a (int): First number
        b (int): Second number

    Returns:
        int: The sum of a and b
    """
    return a + b

Java:

/**
 * Calculates the sum of two numbers
 * @param a First number
 * @param b Second number
 * @return The sum
 */
public int add(int a, int b) {
    return a + b;
}

Step 3: Comment Structure

For functions/methods:

1. Summary: What it does (one line)
2. Parameters: Each parameter explained
3. Returns: What it returns
4. Throws/Raises: Any exceptions (if applicable)
5. Examples: Usage example (if complex)

For classes:

1. Summary: What the class represents
2. Attributes: Key properties
3. Usage: How to instantiate and use

For complex logic:

1. Inline comments: Explain why, not what
2. Section comments: Mark major sections
3. TODO/FIXME: Note improvements needed

Step 4: Write Clear Comments

✅ Good comments:

• Explain WHY, not just WHAT
• Use clear, simple language
• Are concise but complete
• Add value (don't state the obvious)

❌ Bad comments:

// Add a and b
function add(a, b) {
  return a + b;  // Return the sum
}

✅ Better:

/**
 * Combines two monetary values, useful for calculating totals
 * Handles floating point precision for currency
 */
function add(a, b) {
  return Math.round((a + b) * 100) / 100;  // Round to 2 decimals
}

Examples

Example 1: Simple Function

Input:

function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

Output:

/**
 * Calculates the total price of all items in a collection
 * @param {Array<{price: number}>} items - Array of items with price property
 * @returns {number} Total price of all items
 * @example
 * const total = calculateTotal([{price: 10}, {price: 20}]); // Returns 30
 */
function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

Example 2: Complex Function

Input:

def process_data(data, filters=None):
    if not filters:
        filters = []
    result = []
    for item in data:
        valid = True
        for f in filters:
            if not f(item):
                valid = False
                break
        if valid:
            result.append(item)
    return result

Output:

def process_data(data, filters=None):
    """
    Filters a dataset using multiple filter functions.

    Applies each filter function to every item in the dataset.
    Only items that pass all filters are included in the result.

    Args:
        data (list): Collection of items to filter
        filters (list of callable, optional): Filter functions that return True/False.
                                             Defaults to empty list (no filtering).

    Returns:
        list: Filtered dataset containing only items that passed all filters

    Example:
        >>> data = [1, 2, 3, 4, 5]
        >>> is_even = lambda x: x % 2 == 0
        >>> is_positive = lambda x: x > 0
        >>> process_data(data, [is_even, is_positive])
        [2, 4]
    """
    if not filters:
        filters = []

    result = []

    for item in data:
        valid = True

        # Apply each filter - item must pass all filters
        for f in filters:
            if not f(item):
                valid = False
                break  # Skip remaining filters if one fails

        if valid:
            result.append(item)

    return result

Tips

For Beginners

• Start with function/method summaries
• Add parameter descriptions
• Include simple examples

For Intermediate

• Add type information
• Document exceptions
• Include edge cases

For Advanced

• Add algorithmic complexity
• Document thread safety
• Include performance notes

What NOT to Comment

❌ Don't comment obvious code:

// Increment i
i++;

❌ Don't duplicate code in comments:

// Set name to "John"
name = "John";

❌ Don't leave outdated comments:

// TODO: Fix this next week
// (Written 2 years ago)

Remember

• Comments should add value
• Update comments when code changes
• Explain complex logic
• Document public APIs thoroughly
• Keep private code comments minimal but helpful