code-comment-generator

Code Comment Generator

Generate meaningful, maintainable comments and documentation for your code.

Core Capabilities

This skill helps you create effective code documentation by:

1. Analyzing code context - Understanding what the code does and why
2. Matching existing style - Following comment conventions in your codebase
3. Writing clear documentation - Creating function/method/class documentation
4. Adding inline explanations - Explaining complex logic and algorithms
5. Inserting code annotations - Adding TODO, FIXME, and optimization notes

Comment Generation Workflow

Step 1: Analyze Existing Comment Style

Before generating comments, examine the codebase to match style:

Look for:

• Documentation format (docstrings, Javadoc, etc.)
• Comment verbosity level (detailed vs. concise)
• Naming conventions and terminology
• Use of examples in documentation
• Type annotation style

Python Example - Analyze Existing Style:

# If existing code uses this pattern:
def get_user(user_id: int) -> User:
    """
    Retrieve user by ID.

    Args:
        user_id: Unique identifier for the user

    Returns:
        User object if found

    Raises:
        UserNotFoundError: If user doesn't exist
    """
    return db.query(User).get(user_id)

Style Identified:

• Google-style docstrings
• Type hints in signature
• Concise summary line
• Args/Returns/Raises sections
• No examples included

Java Example - Analyze Existing Style:

// If existing code uses this pattern:
/**
 * Retrieves a user by their unique identifier.
 *
 * @param userId the unique identifier for the user
 * @return the User object if found
 * @throws UserNotFoundException if no user exists with the given ID
 */
public User getUser(int userId) throws UserNotFoundException {
    return database.findUser(userId);
}

Style Identified:

• Standard Javadoc format
• Brief summary sentence
• @param, @return, @throws tags
• Formal tone
• No code examples

Step 2: Understand the Code

Analyze the code to understand what to document:

For Functions/Methods:

• What does it do? (purpose)
• Why does it exist? (intent)
• What are the parameters?
• What does it return?
• What exceptions/errors can it raise?
• Are there side effects?
• Are there important preconditions or postconditions?

For Classes:

• What is the class responsible for?
• What design pattern does it implement?
• How should it be used?
• What are the key methods?
• Are there usage examples needed?

For Complex Logic:

• What algorithm is being used?
• Why this approach vs. alternatives?
• What are the edge cases?
• Are there performance considerations?

Step 3: Write Function/Method Documentation

Generate documentation that explains purpose and usage.

Python Example:

# Before (no comments)
def calculate_shipping_cost(items, destination, method):
    base = sum(item.weight * 0.5 for item in items)
    if destination.international:
        base *= 1.5
    if method == 'express':
        base *= 2
    return base + 5

# After (with documentation)
def calculate_shipping_cost(items: List[Item], destination: Address, method: str) -> float:
    """
    Calculate total shipping cost based on items, destination, and shipping method.

    The base cost is calculated from item weights ($0.50 per unit). International
    shipping adds a 50% surcharge, and express shipping doubles the cost. A flat
    $5 handling fee is added to all orders.

    Args:
        items: List of items to ship, each with a weight attribute
        destination: Shipping address with international flag
        method: Shipping method ('standard' or 'express')

    Returns:
        Total shipping cost in USD

    Example:
        >>> items = [Item(weight=2), Item(weight=3)]
        >>> addr = Address(country='USA', international=False)
        >>> calculate_shipping_cost(items, addr, 'standard')
        7.5
    """
    # Calculate base cost from item weights
    base = sum(item.weight * 0.5 for item in items)

    # Apply international surcharge if applicable
    if destination.international:
        base *= 1.5

    # Double cost for express shipping
    if method == 'express':
        base *= 2

    # Add handling fee
    return base + 5

Java Example:

// Before (no comments)
public double calculateShippingCost(List<Item> items, Address destination, String method) {
    double base = items.stream()
        .mapToDouble(item -> item.getWeight() * 0.5)
        .sum();
    if (destination.isInternational()) {
        base *= 1.5;
    }
    if ("express".equals(method)) {
        base *= 2;
    }
    return base + 5;
}

// After (with documentation)
/**
 * Calculates the total shipping cost based on items, destination, and shipping method.
 *
 * <p>The base cost is calculated from item weights ($0.50 per unit). International
 * shipping adds a 50% surcharge, and express shipping doubles the cost. A flat
 * $5 handling fee is added to all orders.
 *
 * @param items the list of items to ship, each with a weight
 * @param destination the shipping address with international flag
 * @param method the shipping method ("standard" or "express")
 * @return the total shipping cost in USD
 * @throws IllegalArgumentException if method is not "standard" or "express"
 */
public double calculateShippingCost(List<Item> items, Address destination, String method) {
    // Calculate base cost from item weights ($0.50 per unit)
    double base = items.stream()
        .mapToDouble(item -> item.getWeight() * 0.5)
        .sum();

    // Apply 50% surcharge for international shipping
    if (destination.isInternational()) {
        base *= 1.5;
    }

    // Double the cost for express shipping
    if ("express".equals(method)) {
        base *= 2;
    }

    // Add $5 handling fee
    return base + 5;
}

Step 4: Add Inline Explanations

Add comments for complex or non-obvious code sections.

When to Add Inline Comments:

• Complex algorithms or formulas
• Non-obvious business logic
• Workarounds or hacks
• Performance optimizations
• Edge case handling
• Regex patterns
• Bit manipulation
• Magic numbers

When NOT to Add Inline Comments:

• Obvious code (e.g., // increment counter for i++)
• Repeating what code already says
• Outdated comments that don't match code

Python Example:

def find_median(numbers):
    """Find the median value in a list of numbers."""
    # Sort is required for median calculation - O(n log n)
    sorted_nums = sorted(numbers)
    n = len(sorted_nums)

    # For even-length lists, median is average of two middle elements
    if n % 2 == 0:
        mid1 = sorted_nums[n // 2 - 1]
        mid2 = sorted_nums[n // 2]
        return (mid1 + mid2) / 2
    # For odd-length lists, median is the middle element
    else:
        return sorted_nums[n // 2]


def validate_email(email):
    """Validate email format using RFC 5322 simplified pattern."""
    # Regex breakdown:
    # ^[a-zA-Z0-9._%+-]+ - local part (before @)
    # @ - literal @ symbol
    # [a-zA-Z0-9.-]+ - domain name
    # \.[a-zA-Z]{2,}$ - top-level domain (at least 2 chars)
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return re.match(pattern, email) is not None


def calculate_discount(price, quantity):
    """Calculate bulk discount for quantity purchases."""
    # Bulk discount tiers (from business requirements doc v3.2)
    # 10+ items: 5% off
    # 50+ items: 10% off
    # 100+ items: 15% off
    if quantity >= 100:
        discount = 0.15
    elif quantity >= 50:
        discount = 0.10
    elif quantity >= 10:
        discount = 0.05
    else:
        discount = 0

    return price * quantity * (1 - discount)

Java Example:

public int findMedian(int[] numbers) {
    // Sort array in-place - required for median calculation
    Arrays.sort(numbers);
    int n = numbers.length;

    // For even-length arrays, return a