Debugging Strategies

Transform debugging from frustrating guesswork into systematic problem-solving with proven strategies, powerful tools, and methodical approaches.

When to Use This Skill

• Tracking down elusive bugs

• Investigating performance issues

• Understanding unfamiliar codebases

• Debugging production issues

• Analyzing crash dumps and stack traces

• Profiling application performance

• Investigating memory leaks

• Debugging distributed systems

Core Principles

1. The Scientific Method

1. Observe: What's the actual behavior?

2. Hypothesize: What could be causing it?

3. Experiment: Test your hypothesis

4. Analyze: Did it prove/disprove your theory?

5. Repeat: Until you find the root cause

2. Debugging Mindset

Don't Assume:

• "It can't be X" - Yes it can

• "I didn't change Y" - Check anyway

• "It works on my machine" - Find out why

Do:

• Reproduce consistently

• Isolate the problem

• Keep detailed notes

• Question everything

• Take breaks when stuck

3. Rubber Duck Debugging

Explain your code and problem out loud (to a rubber duck, colleague, or yourself). Often reveals the issue.

Systematic Debugging Process

Phase 1: Reproduce

## Reproduction Checklist

1. **Can you reproduce it?**

   - Always? Sometimes? Randomly?

   - Specific conditions needed?

   - Can others reproduce it?

2. **Create minimal reproduction**

   - Simplify to smallest example

   - Remove unrelated code

   - Isolate the problem

3. **Document steps**

   - Write down exact steps

   - Note environment details

   - Capture error messages

Phase 2: Gather Information

## Information Collection

1. **Error Messages**

   - Full stack trace

   - Error codes

   - Console/log output

2. **Environment**

   - OS version

   - Language/runtime version

   - Dependencies versions

   - Environment variables

3. **Recent Changes**

   - Git history

   - Deployment timeline

   - Configuration changes

4. **Scope**

   - Affects all users or specific ones?

   - All browsers or specific ones?

   - Production only or also dev?

Phase 3: Form Hypothesis

## Hypothesis Formation

Based on gathered info, ask:

1. **What changed?**

   - Recent code changes

   - Dependency updates

   - Infrastructure changes

2. **What's different?**

   - Working vs broken environment

   - Working vs broken user

   - Before vs after

3. **Where could this fail?**

   - Input validation

   - Business logic

   - Data layer

   - External services

Phase 4: Test & Verify

## Testing Strategies

1. **Binary Search**

   - Comment out half the code

   - Narrow down problematic section

   - Repeat until found

2. **Add Logging**

   - Strategic console.log/print

   - Track variable values

   - Trace execution flow

3. **Isolate Components**

   - Test each piece separately

   - Mock dependencies

   - Remove complexity

4. **Compare Working vs Broken**

   - Diff configurations

   - Diff environments

   - Diff data

Debugging Tools

JavaScript/TypeScript Debugging

// Chrome DevTools Debugger

function processOrder(order: Order) {

  debugger; // Execution pauses here

  const total = calculateTotal(order);

  console.log("Total:", total);

  // Conditional breakpoint

  if (order.items.length > 10) {

    debugger; // Only breaks if condition true

  }

  return total;

}

// Console debugging techniques

console.log("Value:", value); // Basic

console.table(arrayOfObjects); // Table format

console.time("operation");

/* code */ console.timeEnd("operation"); // Timing

console.trace(); // Stack trace

console.assert(value > 0, "Value must be positive"); // Assertion

// Performance profiling

performance.mark("start-operation");

// ... operation code

performance.mark("end-operation");

performance.measure("operation", "start-operation", "end-operation");

console.log(performance.getEntriesByType("measure"));

VS Code Debugger Configuration:

// .vscode/launch.json

{

  "version": "0.2.0",

  "configurations": [

    {

      "type": "node",

      "request": "launch",

      "name": "Debug Program",

      "program": "${workspaceFolder}/src/index.ts",

      "preLaunchTask": "tsc: build - tsconfig.json",

      "outFiles": ["${workspaceFolder}/dist/**/*.js"],

      "skipFiles": ["<node_internals>/**"]

    },

    {

      "type": "node",

      "request": "launch",

      "name": "Debug Tests",

      "program": "${workspaceFolder}/node_modules/jest/bin/jest",

      "args": ["--runInBand", "--no-cache"],

      "console": "integratedTerminal"

    }

  ]

}

Python Debugging

# Built-in debugger (pdb)

import pdb

def calculate_total(items):

    total = 0

    pdb.set_trace()  # Debugger starts here

    for item in items:

        total += item.price * item.quantity

    return total

# Breakpoint (Python 3.7+)

def process_order(order):

    breakpoint()  # More convenient than pdb.set_trace()

    # ... code

# Post-mortem debugging

try:

    risky_operation()

except Exception:

    import pdb

    pdb.post_mortem()  # Debug at exception point

# IPython debugging (ipdb)

from ipdb import set_trace

set_trace()  # Better interface than pdb

# Logging for debugging

import logging

logging.basicConfig(level=logging.DEBUG)

logger = logging.getLogger(__name__)

def fetch_user(user_id):

    logger.debug(f'Fetching user: {user_id}')

    user = db.query(User).get(user_id)

    logger.debug(f'Found user: {user}')

    return user

# Profile performance

import cProfile

import pstats

cProfile.run('slow_function()', 'profile_stats')

stats = pstats.Stats('profile_stats')

stats.sort_stats('cumulative')

stats.print_stats(10)  # Top 10 slowest

Go Debugging

// Delve debugger

// Install: go install github.com/go-delve/delve/cmd/dlv@latest

// Run: dlv debug main.go

import (

    "fmt"

    "runtime"

    "runtime/debug"

)

// Print stack trace

func debugStack() {

    debug.PrintStack()

}

// Panic recovery with debugging

func processRequest() {

    defer func() {

        if r := recover(); r != nil {

            fmt.Println("Panic:", r)

            debug.PrintStack()

        }

    }()

    // ... code that might panic

}

// Memory profiling

import _ "net/http/pprof"

// Visit http://localhost:6060/debug/pprof/

// CPU profiling

import (

    "os"

    "runtime/pprof"

)

f, _ := os.Create("cpu.prof")

pprof.StartCPUProfile(f)

defer pprof.StopCPUProfile()

// ... code to profile

Advanced Debugging Techniques

Technique 1: Binary Search Debugging

# Git bisect for finding regression

git bisect start

git bisect bad                    # Current commit is bad

git bisect good v1.0.0            # v1.0.0 was good

# Git checks out middle commit

# Test it, then:

git bisect good   # if it works

git bisect bad    # if it's broken

# Continue until bug found

git bisect reset  # when done

Technique 2: Differential Debugging

Compare working vs broken:

## What's Different?

| Aspect       | Working     | Broken         |

| ------------ | ----------- | -------------- |

| Environment  | Development | Production     |

| Node version | 18.16.0     | 18.15.0        |

| Data         | Empty DB    | 1M records     |

| User         | Admin       | Regular user   |

| Browser      | Chrome      | Safari         |

| Time         | During day  | After midnight |

Hypothesis: Time-based issue? Check timezone handling.

Technique 3: Trace Debugging

// Function call tracing

function trace(

  target: any,

  propertyKey: string,

  descriptor: PropertyDescriptor,

) {

  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {

    console.log(`Calling ${propertyKey} with args:`, args);

    const result = originalMethod.apply(this, args);

    console.log(`${propertyKey} returned:`, result);

    return result;

  };

  return descriptor;

}

class OrderService {

  @trace

  calculateTotal(items: Item[]): number {

    return items.reduce((sum, item) => sum + item.price, 0);

  }

}

Technique 4: Memory Leak Detection

// Chrome DevTools Memory Profiler

// 1. Take heap snapshot

// 2. Perform action

// 3. Take another snapshot

// 4. Compare snapshots

// Node.js memory debugging

if (process.memoryUsage().heapUsed > 500 * 1024 * 1024) {

  console.warn("High memory usage:", process.memoryUsage());

  // Generate heap dump

  require("v8").writeHeapSnapshot();

}

// Find memory leaks in tests

let beforeMemory: number;

beforeEach(() => {

  beforeMemory = process.memoryUsage().heapUsed;

});

afterEach(() => {

  const afterMemory = process.memoryUsage().heapUsed;

  const diff = afterMemory - beforeMemory;

  if (diff > 10 * 1024 * 1024) {

    // 10MB threshold

    console.warn(`Possible memory leak: ${diff / 1024 / 1024}MB`);

  }

});

Debugging Patterns by Issue Type

Pattern 1: Intermittent Bugs

## Strategies for Flaky Bugs

1. **Add extensive logging**

   - Log timing information

   - Log all state transitions

   - Log external interactions

2. **Look for race conditions**

   - Concurrent access to shared state

   - Async operations completing out of order

   - Missing synchronization

3. **Check timing dependencies**

   - setTimeout/setInterval

   - Promise resolution order

   - Animation frame timing

4. **Stress test**

   - Run many times

   - Vary timing

   - Simulate load

Pattern 2: Performance Issues

## Performance Debugging

1. **Profile first**

   - Don't optimize blindly

   - Measure before and after

   - Find bottlenecks

2. **Common culprits**

   - N+1 queries

   - Unnecessary re-renders

   - Large data processing

   - Synchronous I/O

3. **Tools**

   - Browser DevTools Performance tab

   - Lighthouse

   - Python: cProfile, line_profiler

   - Node: clinic.js, 0x

Pattern 3: Production Bugs

## Production Debugging

1. **Gather evidence**

   - Error tracking (Sentry, Bugsnag)

   - Application logs

   - User reports

   - Metrics/monitoring

2. **Reproduce locally**

   - Use production data (anonymized)

   - Match environment

   - Follow exact steps

3. **Safe investigation**

   - Don't change production

   - Use feature flags

   - Add monitoring/logging

   - Test fixes in staging

Best Practices

• Reproduce First: Can't fix what you can't reproduce

• Isolate the Problem: Remove complexity until minimal case

• Read Error Messages: They're usually helpful

• Check Recent Changes: Most bugs are recent

• Use Version Control: Git bisect, blame, history

• Take Breaks: Fresh eyes see better

• Document Findings: Help future you

• Fix Root Cause: Not just symptoms

Common Debugging Mistakes

• Making Multiple Changes: Change one thing at a time

• Not Reading Error Messages: Read the full stack trace

• Assuming It's Complex: Often it's simple

• Debug Logging in Prod: Remove before shipping

• Not Using Debugger: console.log isn't always best

• Giving Up Too Soon: Persistence pays off

• Not Testing the Fix: Verify it actually works

Quick Debugging Checklist

## When Stuck, Check:

- [ ] Spelling errors (typos in variable names)

- [ ] Case sensitivity (fileName vs filename)

- [ ] Null/undefined values

- [ ] Array index off-by-one

- [ ] Async timing (race conditions)

- [ ] Scope issues (closure, hoisting)

- [ ] Type mismatches

- [ ] Missing dependencies

- [ ] Environment variables

- [ ] File paths (absolute vs relative)

- [ ] Cache issues (clear cache)

- [ ] Stale data (refresh database)