Code Documentation Code Explain

Code Explanation and Analysis

You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform difficult concepts into understandable explanations for developers at all levels.

Use this skill when

• Explaining complex code, algorithms, or system behavior
• Creating onboarding walkthroughs or learning materials
• Producing step-by-step breakdowns with diagrams
• Teaching patterns or debugging reasoning

Do not use this skill when

• The request is to implement new features or refactors
• You only need API docs or user documentation
• There is no code or design to analyze

Context

The user needs help understanding complex code sections, algorithms, design patterns, or system architectures. Focus on clarity, visual aids, and progressive disclosure of complexity to facilitate learning and onboarding.

Requirements

$ARGUMENTS

Instructions

• Assess structure, dependencies, and complexity hotspots.
• Explain the high-level flow, then drill into key components.
• Use diagrams, pseudocode, or examples when useful.
• Call out pitfalls, edge cases, and key terminology.
• If detailed examples are required, open resources/implementation-playbook.md.

Output Format

• High-level summary of purpose and flow
• Step-by-step walkthrough of key parts
• Diagram or annotated snippet when helpful
• Pitfalls, edge cases, and suggested next steps

Resources

• resources/implementation-playbook.md for detailed examples and templates.

Code Explanation and Analysis Implementation Playbook

This file contains detailed patterns, checklists, and code samples referenced by the skill.

Instructions

1. Code Comprehension Analysis

Analyze the code to determine complexity and structure:

Code Complexity Assessment

import ast
import re
from typing import Dict, List, Tuple

class CodeAnalyzer:
    def analyze_complexity(self, code: str) -> Dict:
        """
        Analyze code complexity and structure
        """
        analysis = {
            'complexity_score': 0,
            'concepts': [],
            'patterns': [],
            'dependencies': [],
            'difficulty_level': 'beginner'
        }
        
        # Parse code structure
        try:
            tree = ast.parse(code)
            
            # Analyze complexity metrics
            analysis['metrics'] = {
                'lines_of_code': len(code.splitlines()),
                'cyclomatic_complexity': self._calculate_cyclomatic_complexity(tree),
                'nesting_depth': self._calculate_max_nesting(tree),
                'function_count': len([n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]),
                'class_count': len([n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)])
            }
            
            # Identify concepts used
            analysis['concepts'] = self._identify_concepts(tree)
            
            # Detect design patterns
            analysis['patterns'] = self._detect_patterns(tree)
            
            # Extract dependencies
            analysis['dependencies'] = self._extract_dependencies(tree)
            
            # Determine difficulty level
            analysis['difficulty_level'] = self._assess_difficulty(analysis)
            
        except SyntaxError as e:
            analysis['parse_error'] = str(e)
            
        return analysis
    
    def _identify_concepts(self, tree) -> List[str]:
        """
        Identify programming concepts used in the code
        """
        concepts = []
        
        for node in ast.walk(tree):
            # Async/await
            if isinstance(node, (ast.AsyncFunctionDef, ast.AsyncWith, ast.AsyncFor)):
                concepts.append('asynchronous programming')
            
            # Decorators
            elif isinstance(node, ast.FunctionDef) and node.decorator_list:
                concepts.append('decorators')
            
            # Context managers
            elif isinstance(node, ast.With):
                concepts.append('context managers')
            
            # Generators
            elif isinstance(node, ast.Yield):
                concepts.append('generators')
            
            # List/Dict/Set comprehensions
            elif isinstance(node, (ast.ListComp, ast.DictComp, ast.SetComp)):
                concepts.append('comprehensions')
            
            # Lambda functions
            elif isinstance(node, ast.Lambda):
                concepts.append('lambda functions')
            
            # Exception handling
            elif isinstance(node, ast.Try):
                concepts.append('exception handling')
                
        return list(set(concepts))

2. Visual Explanation Generation

Create visual representations of code flow:

Flow Diagram Generation

class VisualExplainer:
    def generate_flow_diagram(self, code_structure):
        """
        Generate Mermaid diagram showing code flow
        """
        diagram = "```mermaid\nflowchart TD\n"
        
        # Example: Function call flow
        if code_structure['type'] == 'function_flow':
            nodes = []
            edges = []
            
            for i, func in enumerate(code_structure['functions']):
                node_id = f"F{i}"
                nodes.append(f"    {node_id}[{func['name']}]")
                
                # Add function details
                if func.get('parameters'):
                    nodes.append(f"    {node_id}_params[/{', '.join(func['parameters'])}/]")
                    edges.append(f"    {node_id}_params --> {node_id}")
                
                # Add return value
                if func.get('returns'):
                    nodes.append(f"    {node_id}_return[{func['returns']}]")
                    edges.append(f"    {node_id} --> {node_id}_return")
                
                # Connect to called functions
                for called in func.get('calls', []):
                    called_id = f"F{code_structure['function_map'][called]}"
                    edges.append(f"    {node_id} --> {called_id}")
            
            diagram += "\n".join(nodes) + "\n"
            diagram += "\n".join(edges) + "\n"
            
        diagram += "```"
        return diagram
    
    def generate_class_diagram(self, classes):
        """
        Generate UML-style class diagram
        """
        diagram = "```mermaid\nclassDiagram\n"
        
        for cls in classes:
            # Class definition
            diagram += f"    class {cls['name']} {{\n"
            
            # Attributes
            for attr in cls.get('attributes', []):
                visibility = '+' if attr['public'] else '-'
                diagram += f"        {visibility}{attr['name']} : {attr['type']}\n"
            
            # Methods
            for method in cls.get('methods', []):
                visibility = '+' if method['public'] else '-'
                params = ', '.join(method.get('params', []))
                diagram += f"        {visibility}{method['name']}({params}) : {method['returns']}\n"
            
            diagram += "    }\n"
            
            # Relationships
            if cls.get('inherits'):
                diagram += f"    {cls['inherits']} <|-- {cls['name']}\n"
            
            for composition in cls.get('compositions', []):
                diagram += f"    {cls['name']} *-- {composition}\n"
            
        diagram += "```"
        return diagram

3. Step-by-Step Explanation

Break down complex code into digestible steps:

Progressive Explanation

def generate_step_by_step_explanation(self, code, analysis):
    """
    Create progressive explanation from simple to complex
    """
    explanation = {
        'overview': self._generate_overview(code, analysis),
        'steps': [],
        'deep_dive': [],
        'examples': []
    }
    
    # Level 1: High-level overview
    explanation['overview'] = f"""
## What This Code Does

{self._summarize_purpose(code, analysis)}

**Key Concepts**: {', '.join(analysis['concepts'])}
**Difficulty Level**: {analysis['difficulty_level'].capitalize()}
"""
    
    # Level 2: Step-by-step breakdown
    if analysis.get('functions'):
        for i, func in enumerate(analysis['functions']):
            step = f"""
### Step {i+1}: {func['name']}

**Purpose**: {self._explain_function_purpose(func)}

**How it works**:
"""
            # Break down function logic
            for j, logic_step in enumerate(self._analyze_function_logic(func)):
                step += f"{j+1}. {logic_step}\n"
            
            # Add visual flow if complex
            if func['complexity'] > 5:
                step += f"\n{self._generate_function_flow(func)}\n"
            
            explanation['steps'].append(step)
    
    # Level 3: Deep dive into complex parts
    for concept in analysis['concepts']:
        deep_dive = self._explain_concept(concept, code)
        explanation['deep_dive'].append(deep_dive)
    
    return explanation

def _explain_concept(self, concept, code):
    """
    Explain programming concept with examples
    """
    explanations = {
        'decorators': '''
## Understanding Decorators

Decorators are a way to modify or enhance functions without changing their code directly.

**Simple Analogy**: Think of a decorator like gift wrapping - it adds something extra around the original item.

**How it works**:

This decorator:

@timer def slow_function(): time.sleep(1)

Is equivalent to:

def slow_function(): time.sleep(1) slow_function = timer(slow_function)

**In this code**: The decorator is used to {specific_use_in_code}
''',
        'generators': '''
## Understanding Generators

Generators produce values one at a time, saving memory by not creating all values at once.

**Simple Analogy**: Like a ticket dispenser that gives one ticket at a time, rather than printing all tickets upfront.

**How it works**:

Generator function

def count_up_to(n): i = 0 while i < n: yield i # Produces one value and pauses i += 1

Using the generator

for num in count_up_to(5): print(num) # Prints 0, 1, 2, 3, 4

**In this code**: The generator is used to {specific_use_in_code}
'''
    }
    
    return explanations.get(concept, f"Explanation for {concept}")

4. Algorithm Visualization

Visualize algorithm execution:

Algorithm Step Visualization

class AlgorithmVisualizer:
    def visualize_sorting_algorithm(self, algorithm_name, array):
        """
        Create step-by-step visualization of sorting algorithm
        """
        steps = []
        
        if algorithm_name == 'bubble_sort':
            steps.append("""
## Bubble Sort Visualization

**Initial Array**: [5, 2, 8, 1, 9]

### How Bubble Sort Works:
1. Compare adjacent elements
2. Swap if they're in wrong order
3. Repeat until no swaps needed

### Step-by-Step Execution:
""")
            
            # Simulate bubble sort with visualization
            arr = array.copy()
            n = len(arr)
            
            for i in range(n):
                swapped = False
                step_viz = f"\n**Pass {i+1}**:\n"
                
                for j in range(0, n-i-1):
                    # Show comparison
                    step_viz += f"Compare [{arr[j]}] and [{arr[j+1]}]: "
                    
                    if arr[j] > arr[j+1]:
                        arr[j], arr[j+1] = arr[j+1], arr[j]
                        step_viz += f"Swap → {arr}\n"
                        swapped = True
                    else:
                        step_viz += "No swap needed\n"
                
                steps.append(step_viz)
                
                if not swapped:
                    steps.append(f"\n✅ Array is sorted: {arr}")
                    break
        
        return '\n'.join(steps)
    
    def visualize_recursion(self, func_name, example_input):
        """
        Visualize recursive function calls
        """
        viz = f"""
## Recursion Visualization: {func_name}

### Call Stack Visualization:

{func_name}({example_input}) │ ├─> Base case check: {example_input} == 0? No ├─> Recursive call: {func_name}({example_input - 1}) │ │ │ ├─> Base case check: {example_input - 1} == 0? No │ ├─> Recursive call: {func_name}({example_input - 2}) │ │ │ │ │ ├─> Base case check: 1 == 0? No │ │ ├─> Recursive call: {func_name}(0) │ │ │ │ │ │ │ └─> Base case: Return 1 │ │ │ │ │ └─> Return: 1 1 = 1 │ │ │ └─> Return: 2 1 = 2 │ └─> Return: 3 * 2 = 6

**Final Result**: {func_name}({example_input}) = 6
"""
        return viz

5. Interactive Examples

Generate interactive examples for better understanding:

Code Playground Examples

def generate_interactive_examples(self, concept):
    """
    Create runnable examples for concepts
    """
    examples = {
        'error_handling': '''
## Try It Yourself: Error Handling

### Example 1: Basic Try-Except

def safe_divide(a, b): try: result = a / b print(f"{a} / {b} = {result}") return result except ZeroDivisionError: print("Error: Cannot divide by zero!") return None except TypeError: print("Error: Please provide numbers only!") return None finally: print("Division attempt completed")

Test cases - try these:

safe_divide(10, 2) # Success case safe_divide(10, 0) # Division by zero safe_divide(10, "2") # Type error

### Example 2: Custom Exceptions

class ValidationError(Exception): """Custom exception for validation errors""" pass

def validate_age(age): try: age = int(age) if age < 0: raise ValidationError("Age cannot be negative") if age > 150: raise ValidationError("Age seems unrealistic") return age except ValueError: raise ValidationError("Age must be a number")

Try these examples:

try: validate_age(25) # Valid validate_age(-5) # Negative age validate_age("abc") # Not a number except ValidationError as e: print(f"Validation failed: {e}")

### Exercise: Implement Your Own
Try implementing a function that:
1. Takes a list of numbers
2. Returns their average
3. Handles empty lists
4. Handles non-numeric values
5. Uses appropriate exception handling
''',
        'async_programming': '''
## Try It Yourself: Async Programming

### Example 1: Basic Async/Await

import asyncio import time

async def slow_operation(name, duration): print(f"{name} started...") await asyncio.sleep(duration) print(f"{name} completed after {duration}s") return f"{name} result"

async def main():

Sequential execution (slow)

start = time.time() await slow_operation("Task 1", 2) await slow_operation("Task 2", 2) print(f"Sequential time: {time.time() - start:.2f}s")

Concurrent execution (fast)

start = time.time() results = await asyncio.gather( slow_operation("Task 3", 2), slow_operation("Task 4", 2) ) print(f"Concurrent time: {time.time() - start:.2f}s") print(f"Results: {results}")

Run it:

asyncio.run(main())

### Example 2: Real-world Async Pattern

async def fetch_data(url): """Simulate API call""" await asyncio.sleep(1) # Simulate network delay return f"Data from {url}"

async def process_urls(urls): tasks = [fetch_data(url) for url in urls] results = await asyncio.gather(*tasks) return results

Try with different URLs:

urls = ["api.example.com/1", "api.example.com/2", "api.example.com/3"] results = asyncio.run(process_urls(urls)) print(results)

'''
    }
    
    return examples.get(concept, "No example available")

6. Design Pattern Explanation

Explain design patterns found in code:

Pattern Recognition and Explanation

class DesignPatternExplainer:
    def explain_pattern(self, pattern_name, code_example):
        """
        Explain design pattern with diagrams and examples
        """
        patterns = {
            'singleton': '''
## Singleton Pattern

### What is it?
The Singleton pattern ensures a class has only one instance and provides global access to it.

### When to use it?
- Database connections
- Configuration managers
- Logging services
- Cache managers

### Visual Representation:

classDiagram class Singleton { -instance: Singleton -__init__() +getInstance(): Singleton } Singleton --> Singleton : returns same instance

### Implementation in this code:
{code_analysis}

### Benefits:
✅ Controlled access to single instance
✅ Reduced namespace pollution
✅ Permits refinement of operations

### Drawbacks:
❌ Can make unit testing difficult
❌ Violates Single Responsibility Principle
❌ Can hide dependencies

### Alternative Approaches:
1. Dependency Injection
2. Module-level singleton
3. Borg pattern
''',
            'observer': '''
## Observer Pattern

### What is it?
The Observer pattern defines a one-to-many dependency between objects so that when one object changes state, all dependents are notified.

### When to use it?
- Event handling systems
- Model-View architectures
- Distributed event handling

### Visual Representation:

classDiagram class Subject { +attach(Observer) +detach(Observer) +notify() } class Observer { +update() } class ConcreteSubject { -state +getState() +setState() } class ConcreteObserver { -subject +update() } Subject <|-- ConcreteSubject Observer <|-- ConcreteObserver ConcreteSubject --> Observer : notifies ConcreteObserver --> ConcreteSubject : observes

### Implementation in this code:
{code_analysis}

### Real-world Example:

Newsletter subscription system

class Newsletter: def __init__(self): self._subscribers = [] self._latest_article = None

def subscribe(self, subscriber): self._subscribers.append(subscriber)

def unsubscribe(self, subscriber): self._subscribers.remove(subscriber)

def publish_article(self, article): self._latest_article = article self._notify_subscribers()

def _notify_subscribers(self): for subscriber in self._subscribers: subscriber.update(self._latest_article)

class EmailSubscriber: def __init__(self, email): self.email = email

def update(self, article): print(f"Sending email to {self.email}: New article - {article}")

'''
        }
        
        return patterns.get(pattern_name, "Pattern explanation not available")

7. Common Pitfalls and Best Practices

Highlight potential issues and improvements:

Code Review Insights

def analyze_common_pitfalls(self, code):
    """
    Identify common mistakes and suggest improvements
    """
    issues = []
    
    # Check for common Python pitfalls
    pitfall_patterns = [
        {
            'pattern': r'except:',
            'issue': 'Bare except clause',
            'severity': 'high',
            'explanation': '''
## ⚠️ Bare Except Clause

**Problem**: `except:` catches ALL exceptions, including system exits and keyboard interrupts.

**Why it's bad**:
- Hides programming errors
- Makes debugging difficult
- Can catch exceptions you didn't intend to handle

**Better approach**:

Bad

try: risky_operation() except: print("Something went wrong")

Good

try: risky_operation() except (ValueError, TypeError) as e: print(f"Expected error: {e}") except Exception as e: logger.error(f"Unexpected error: {e}") raise

'''
        },
        {
            'pattern': r'def.*\(\s*\):.*global',
            'issue': 'Global variable usage',
            'severity': 'medium',
            'explanation': '''
## ⚠️ Global Variable Usage

**Problem**: Using global variables makes code harder to test and reason about.

**Better approaches**:
1. Pass as parameter
2. Use class attributes
3. Use dependency injection
4. Return values instead

**Example refactor**:

Bad

count = 0 def increment(): global count count += 1

Good

class Counter: def __init__(self): self.count = 0

def increment(self): self.count += 1 return self.count

'''
        }
    ]
    
    for pitfall in pitfall_patterns:
        if re.search(pitfall['pattern'], code):
            issues.append(pitfall)
    
    return issues

8. Learning Path Recommendations

Suggest resources for deeper understanding:

Personalized Learning Path

def generate_learning_path(self, analysis):
    """
    Create personalized learning recommendations
    """
    learning_path = {
        'current_level': analysis['difficulty_level'],
        'identified_gaps': [],
        'recommended_topics': [],
        'resources': []
    }
    
    # Identify knowledge gaps
    if 'async' in analysis['concepts'] and analysis['difficulty_level'] == 'beginner':
        learning_path['identified_gaps'].append('Asynchronous programming fundamentals')
        learning_path['recommended_topics'].extend([
            'Event loops',
            'Coroutines vs threads',
            'Async/await syntax',
            'Concurrent programming patterns'
        ])
    
    # Add resources
    learning_path['resources'] = [
        {
            'topic': 'Async Programming',
            'type': 'tutorial',
            'title': 'Async IO in Python: A Complete Walkthrough',
            'url': 'https://realpython.com/async-io-python/',
            'difficulty': 'intermediate',
            'time_estimate': '45 minutes'
        },
        {
            'topic': 'Design Patterns',
            'type': 'book',
            'title': 'Head First Design Patterns',
            'difficulty': 'beginner-friendly',
            'format': 'visual learning'
        }
    ]
    
    # Create structured learning plan
    learning_path['structured_plan'] = f"""
## Your Personalized Learning Path

### Week 1-2: Fundamentals
- Review basic concepts: {', '.join(learning_path['recommended_topics'][:2])}
- Complete exercises on each topic
- Build a small project using these concepts

### Week 3-4: Applied Learning
- Study the patterns in this codebase
- Refactor a simple version yourself
- Compare your approach with the original

### Week 5-6: Advanced Topics
- Explore edge cases and optimizations
- Learn about alternative approaches
- Contribute to open source projects using these patterns

### Practice Projects:
1. **Beginner**: {self._suggest_beginner_project(analysis)}
2. **Intermediate**: {self._suggest_intermediate_project(analysis)}
3. **Advanced**: {self._suggest_advanced_project(analysis)}
"""
    
    return learning_path

Output Format

1. Complexity Analysis: Overview of code complexity and concepts used 2. Visual Diagrams: Flow charts, class diagrams, and execution visualizations 3. Step-by-Step Breakdown: Progressive explanation from simple to complex 4. Interactive Examples: Runnable code samples to experiment with 5. Common Pitfalls: Issues to avoid with explanations 6. Best Practices: Improved approaches and patterns 7. Learning Resources: Curated resources for deeper understanding 8. Practice Exercises: Hands-on challenges to reinforce learning

Focus on making complex code accessible through clear explanations, visual aids, and practical examples that build understanding progressively.