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)

   • What does this code do?
   • What problem does it solve?

2. Core Logic (2-4 bullet points)

   • Key algorithms or approaches used
   • Important data transformations
   • Critical control flow decisions

3. Key Details

   • Input parameters and their purposes
   • Return values and their meaning
   • Important side effects or state changes
   • Dependencies on external libraries or modules

4. Notable Patterns (if applicable)

   • Design patterns used
   • Optimization techniques
   • 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)

   • What does this codebase do?
   • What is its primary use case or domain?

2. Architecture Overview

   • Overall design pattern (MVC, microservices, layered, etc.)
   • Key architectural decisions
   • Technology stack

3. Main Components (list with brief descriptions)

   • List 5-10 major modules/packages
   • One-line description for each
   • Indicate relationships between components

4. Entry Points

   • Main execution files
   • Key API endpoints or interfaces
   • 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

   • Start with entry points (main files, init.py, index files)
   • Examine directory structure for organization patterns
   • Look for README, documentation, or comments
   • Identify configuration files

2. Identify patterns

   • Recognize common design patterns
   • Note architectural styles
   • Identify framework conventions

3. Focus on intent over implementation

   • Explain what and why before how
   • Highlight business logic over boilerplate
   • 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