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:

javascript

/**
 * 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:

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:

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:

•Summary: What it does (one line)
•Parameters: Each parameter explained
•Returns: What it returns
•Throws/Raises: Any exceptions (if applicable)
•Examples: Usage example (if complex)

For classes:

•Summary: What the class represents
•Attributes: Key properties
•Usage: How to instantiate and use

For complex logic:

•Inline comments: Explain why, not what
•Section comments: Mark major sections
•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:

javascript

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

✅ Better:

javascript

/**
 * 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:

javascript

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

Output:

javascript

/**
 * 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:

python

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:

python

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:

javascript

// Increment i
i++;

❌ Don't duplicate code in comments:

javascript

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

❌ Don't leave outdated comments:

javascript

// 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