claudekit/.claude/skills/documentation/references/code-docs.md

Code Documentation Patterns

Python Docstrings (Google Style)

def calculate_discount(price: float, percentage: float) -> float:
    """Calculate discounted price.

    Args:
        price: Original price in dollars.
        percentage: Discount percentage (0-100).

    Returns:
        The discounted price.

    Raises:
        ValueError: If percentage is not between 0 and 100.

    Example:
        >>> calculate_discount(100.0, 20)
        80.0
    """

TypeScript JSDoc

/**
 * Calculate discounted price.
 *
 * @param price - Original price in dollars
 * @param percentage - Discount percentage (0-100)
 * @returns The discounted price
 * @throws {RangeError} If percentage is not between 0 and 100
 *
 * @example
 * calculateDiscount(100, 20); // returns 80
 */

When to Add Inline Comments

• Explain why, not what — # Retry 3x because upstream API is flaky
• Document workarounds — // Safari doesn't support this API, fallback to...
• Clarify non-obvious logic — # O(1) amortized via lazy deletion
• Mark TODOs with context — # TODO(#123): remove after migration complete

When NOT to Comment

• Restating the code: i += 1 # increment i by 1
• Obvious function names: def get_user_by_id needs no docstring explaining it gets a user by ID
• Commented-out code — delete it, git has history