code-summarizer

Code Summarizer

Generate clear, concise summaries of source code at any scale - from individual functions to entire codebases.

Overview

This skill helps analyze and summarize code by adapting the level of detail to the code's scale:

• Small-scale code (functions, classes, small files): Provide focused summaries of intention and implementation
• Large-scale code (modules, packages, entire repositories): Provide hierarchical summaries with progressive drill-down

Workflow Decision Tree

User provides code → Assess scale
    ├─ Small-scale (< 200 lines, single file/function)
    │   └─ Generate focused summary
    │
    └─ Large-scale (> 200 lines, multiple files/modules)
        ├─ Generate high-level overview
        ├─ List main modules/components
        └─ Prompt user to select specific parts for detailed analysis

Small-Scale Code Summarization

For functions, classes, or small files (typically < 200 lines), provide a focused summary that includes:

Summary Structure

1. Purpose Statement (1-2 sentences)
2. What does this code do?
3. What problem does it solve?

1. Core Logic (2-4 bullet points)
2. Key algorithms or approaches used
3. Important data transformations
4. Critical control flow decisions

1. Key Details
2. Input parameters and their purposes
3. Return values and their meaning
4. Important side effects or state changes
5. Dependencies on external libraries or modules

1. Notable Patterns (if applicable)
2. Design patterns used
3. Optimization techniques
4. Error handling approaches

Example Format

## Summary

**Purpose**: This function validates user email addresses and normalizes them to lowercase format before database storage.

**Core Logic**:
- Uses regex pattern matching to validate email format (RFC 5322 compliant)
- Strips whitespace and converts to lowercase for consistency
- Checks against a blocklist of disposable email domains
- Logs validation failures for security monitoring

**Key Details**:
- Input: `email` (string) - raw email address from user input
- Returns: `normalized_email` (string) or raises `ValidationError`
- Side effect: Logs to `security.log` on validation failure
- Dependencies: `re`, `logging`, custom `EmailBlocklist` class

**Notable Patterns**:
- Uses early return pattern for validation failures
- Implements defensive programming with input sanitization

Large-Scale Code Summarization

For modules, packages, or entire repositories (typically > 200 lines or multiple files), use a hierarchical approach:

Phase 1: High-Level Overview

Provide a concise overview that includes:

1. Project Purpose (2-3 sentences)
2. What does this codebase do?
3. What is its primary use case or domain?

1. Architecture Overview
2. Overall design pattern (MVC, microservices, layered, etc.)
3. Key architectural decisions
4. Technology stack

1. Main Components (list with brief descriptions)
2. List 5-10 major modules/packages
3. One-line description for each
4. Indicate relationships between components

1. Entry Points
2. Main execution files
3. Key API endpoints or interfaces
4. Configuration files

Phase 2: Interactive Drill-Down

After providing the overview, prompt the user to select specific areas for detailed analysis:

## Detailed Analysis Available

I can provide more detailed summaries of specific components:

1. **[Component Name]** - [Brief description]
2. **[Component Name]** - [Brief description]
3. **[Component Name]** - [Brief description]
...

Which component(s) would you like me to analyze in detail? You can:
- Select one or more by number
- Ask about specific functionality (e.g., "How does authentication work?")
- Request a specific file or module by name

Phase 3: Detailed Component Analysis

When user selects a component, provide a detailed summary using the small-scale format adapted for the component:

• Purpose and responsibilities
• Key classes/functions within the component
• Interactions with other components
• Important algorithms or business logic
• Configuration and dependencies

Best Practices

Code Analysis Approach

1. Read strategically
2. Start with entry points (main files, __init__.py, index files)
3. Examine directory structure for organization patterns
4. Look for README, documentation, or comments
5. Identify configuration files

1. Identify patterns
2. Recognize common design patterns
3. Note architectural styles
4. Identify framework conventions

1. Focus on intent over implementation
2. Explain what and why before how
3. Highlight business logic over boilerplate
4. Emphasize key algorithms over routine operations

Writing Style

• Be concise: Avoid unnecessary verbosity
• Be specific: Use concrete examples and actual names from the code
• Be hierarchical: Start broad, then drill down
• Be actionable: Help users understand how to use or modify the code

Handling Different Languages

Adapt terminology and patterns to the language:

• Python: Modules, packages, decorators, list comprehensions
• JavaScript: Modules, components, promises, async/await
• Java: Packages, classes, interfaces, annotations
• C/C++: Headers, source files, namespaces, templates
• Go: Packages, goroutines, channels, interfaces

Common Scenarios

Scenario 1: Understanding a New Codebase

User: "Can you summarize this repository?"

Response approach:

1. Analyze directory structure
2. Read main entry points and README
3. Provide high-level overview with component list
4. Offer to drill down into specific areas

Scenario 2: Explaining a Specific Function

User: "What does this function do?" [provides code]

Response approach:

1. Identify function purpose
2. Explain core logic step-by-step
3. Note inputs, outputs, and side effects
4. Highlight any notable patterns or concerns

Scenario 3: Comparing Implementations

User: "Summarize these two implementations and compare them"

Response approach:

1. Summarize each implementation separately
2. Identify key differences in approach
3. Compare trade-offs (performance, readability, maintainability)
4. Recommend based on context if appropriate

Scenario 4: Legacy Code Understanding

User: "Help me understand this old code"

Response approach:

1. Identify the era/style of the code
2. Explain outdated patterns or conventions
3. Summarize what it does in modern terms
4. Suggest modern equivalents if relevant

Output Format Guidelines

For Small-Scale Code

Use clear markdown with:

• Heading for the summary
• Bullet points for core logic
• Code blocks for examples if helpful
• Bold for emphasis on key terms

For Large-Scale Code

Use structured markdown with:

• Clear section headings
• Numbered or bulleted lists for components
• Tables for comparing multiple items
• Collapsible sections for optional details (if supported)

Code References

When referencing specific code elements:

• Use backticks for function/class/variable names
• Include file paths when relevant: src/utils/validator.py:validate_email()
• Use line numbers for large files: lines 45-67

Limitations and Considerations

• Context limits: For very large codebases, may need to analyze in chunks
• Missing context: May need to ask clarifying questions about business logic
• Language expertise: Summaries are most accurate for well-known languages and frameworks
• Dynamic behavior: Cannot fully analyze runtime behavior without execution
• External dependencies: May not have full context for third-party libraries

When encountering limitations, acknowledge them and offer alternative approaches or ask for additional context.