3.2 — The debugging process

In this lesson, you'll learn about the systematic approach to debugging, which is the process of finding and fixing bugs in your code. Effective debugging is both an art and a science that requires patience, methodical thinking, and practice.

What is debugging?

Debugging is the process of identifying, isolating, and fixing problems (bugs) in your code. The term "bug" comes from an actual moth that was found stuck in early computer hardware in 1947 by Grace Hopper, but today it refers to any error in software.

The debugging process typically follows these stages:

1. Recognition: Realizing there's a problem
2. Isolation: Finding where the problem occurs
3. Identification: Understanding what's causing the problem
4. Resolution: Fixing the problem
5. Verification: Confirming the fix works correctly

The debugging mindset

Before diving into techniques, it's important to develop the right mindset for debugging:

Stay calm and methodical

When your program doesn't work as expected, it's easy to get frustrated. However, effective debugging requires:

• Patience: Bugs can be elusive and take time to find
• Systematic approach: Random changes rarely solve problems
• Persistence: Some bugs require multiple attempts to identify and fix
• Curiosity: Ask "why" something is happening, not just "how to fix it"

Think like a detective

Debugging is like detective work. You need to:

• Gather evidence: Collect information about the bug
• Form hypotheses: Make educated guesses about the cause
• Test theories: Write code to confirm or refute your hypotheses
• Follow the clues: Let the evidence guide your investigation

The systematic debugging process

Step 1: Recognize that there's a problem

Problems can manifest in several ways:

#include <iostream>

int calculateAverage(int a, int b, int c)
{
    return (a + b + c) / 3;  // Integer division - potential problem
}

int main()
{
    int avg1 = calculateAverage(10, 15, 20);     // Should be 15
    int avg2 = calculateAverage(10, 11, 12);     // Should be 11
    int avg3 = calculateAverage(1, 2, 3);        // Should be 2
    
    std::cout << "Average of 10, 15, 20: " << avg1 << std::endl;
    std::cout << "Average of 10, 11, 12: " << avg2 << std::endl;
    std::cout << "Average of 1, 2, 3: " << avg3 << std::endl;
    
    return 0;
}

Output:

Average of 10, 15, 20: 15
Average of 10, 11, 12: 11
Average of 1, 2, 3: 2

Problem recognition: The first two results look correct, but what about cases where the division should result in a decimal?

#include <iostream>

int calculateAverage(int a, int b, int c)
{
    return (a + b + c) / 3;  // Integer division problem
}

int main()
{
    int avg = calculateAverage(1, 2, 2);  // Should be 1.67, but returns 1
    std::cout << "Average of 1, 2, 2: " << avg << std::endl;
    
    return 0;
}

Output:

Average of 1, 2, 2: 1

Problem identified: Integer division is truncating decimal results.

Step 2: Reproduce the problem

Before you can fix a bug, you need to be able to make it happen consistently:

#include <iostream>

// Buggy function - sometimes works, sometimes doesn't
int divide(int numerator, int denominator)
{
    return numerator / denominator;  // No zero-check
}

int main()
{
    // Test cases to reproduce the problem
    std::cout << "Testing divide function:" << std::endl;
    
    std::cout << "10 / 2 = " << divide(10, 2) << std::endl;     // Works fine
    std::cout << "15 / 3 = " << divide(15, 3) << std::endl;     // Works fine
    std::cout << "7 / 0 = ";
    
    // This will cause undefined behavior or crash
    // std::cout << divide(7, 0) << std::endl;
    std::cout << "ERROR: Division by zero!" << std::endl;
    
    return 0;
}

Output:

Testing divide function:
10 / 2 = 5
15 / 3 = 5
7 / 0 = ERROR: Division by zero!

Step 3: Isolate the problem

Once you can reproduce the bug, narrow down where it occurs:

#include <iostream>

int multiply(int x, int y)
{
    return x * y;
}

int add(int x, int y)
{
    return x + y;
}

int calculateTotal(int a, int b, int c)
{
    int step1 = multiply(a, 2);      // Double first number
    int step2 = add(step1, b);       // Add second number
    int step3 = multiply(step2, c);  // Multiply by third number
    return step3;
}

int main()
{
    int result = calculateTotal(5, 10, 3);
    std::cout << "Result: " << result << std::endl;
    
    // Expected: (5 * 2 + 10) * 3 = (10 + 10) * 3 = 20 * 3 = 60
    // Let's verify each step
    
    std::cout << "\nDebugging step by step:" << std::endl;
    int step1 = multiply(5, 2);
    std::cout << "Step 1 (5 * 2): " << step1 << std::endl;
    
    int step2 = add(step1, 10);
    std::cout << "Step 2 (" << step1 << " + 10): " << step2 << std::endl;
    
    int step3 = multiply(step2, 3);
    std::cout << "Step 3 (" << step2 << " * 3): " << step3 << std::endl;
    
    return 0;
}

Output:

Result: 60

Debugging step by step:
Step 1 (5 * 2): 10
Step 2 (10 + 10): 20
Step 3 (20 * 3): 60

Step 4: Form hypotheses

Based on your observations, form theories about what might be causing the problem:

#include <iostream>

// Bug: Function doesn't handle negative numbers correctly
bool isPositive(int number)
{
    if (number > 0)
        return true;
    else
        return false;  // This returns false for zero too
}

int main()
{
    // Test cases reveal the hypothesis
    std::cout << "Testing isPositive function:" << std::endl;
    std::cout << "isPositive(5): " << std::boolalpha << isPositive(5) << std::endl;
    std::cout << "isPositive(-3): " << std::boolalpha << isPositive(-3) << std::endl;
    std::cout << "isPositive(0): " << std::boolalpha << isPositive(0) << std::endl;
    
    // Hypothesis: The function incorrectly classifies zero as not positive
    // This might be correct or incorrect depending on requirements
    
    return 0;
}

Output:

Testing isPositive function:
isPositive(5): true
isPositive(-3): false
isPositive(0): false

Hypothesis: Is zero supposed to be considered positive? This depends on the requirements.

Step 5: Test your hypotheses

Write code to test your theories:

#include <iostream>

// Original buggy version
int fibonacci_buggy(int n)
{
    if (n <= 1)
        return n;
    return fibonacci_buggy(n - 1) + fibonacci_buggy(n - 2);
}

// Hypothesis: The function is correct but inefficient
// Let's test with small values first
void testFibonacci()
{
    std::cout << "Testing Fibonacci function:" << std::endl;
    
    for (int i = 0; i <= 10; ++i)
    {
        std::cout << "fib(" << i << ") = " << fibonacci_buggy(i) << std::endl;
    }
    
    // Hypothesis test: Is it just slow, or actually wrong?
    std::cout << "\nExpected Fibonacci sequence: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55" << std::endl;
}

int main()
{
    testFibonacci();
    return 0;
}

Output:

Testing Fibonacci function:
fib(0) = 0
fib(1) = 1
fib(2) = 1
fib(3) = 2
fib(4) = 3
fib(5) = 5
fib(6) = 8
fib(7) = 13
fib(8) = 21
fib(9) = 34
fib(10) = 55

Expected Fibonacci sequence: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55

Conclusion: The function is correct but becomes extremely slow for larger values due to repeated calculations.

Step 6: Fix the problem

Once you understand the issue, implement a fix:

#include <iostream>

// Fixed version with better performance
int fibonacci_fixed(int n)
{
    if (n <= 1)
        return n;
    
    int prev1 = 0;
    int prev2 = 1;
    int current;
    
    for (int i = 2; i <= n; ++i)
    {
        current = prev1 + prev2;
        prev1 = prev2;
        prev2 = current;
    }
    
    return current;
}

int main()
{
    std::cout << "Fixed Fibonacci function:" << std::endl;
    
    for (int i = 0; i <= 15; ++i)
    {
        std::cout << "fib(" << i << ") = " << fibonacci_fixed(i) << std::endl;
    }
    
    return 0;
}

Output:

Fixed Fibonacci function:
fib(0) = 0
fib(1) = 1
fib(2) = 1
fib(3) = 2
fib(4) = 3
fib(5) = 5
fib(6) = 8
fib(7) = 13
fib(8) = 21
fib(9) = 34
fib(10) = 55
fib(11) = 89
fib(12) = 144
fib(13) = 233
fib(14) = 377
fib(15) = 610

Step 7: Verify the fix

Make sure your fix actually solves the problem and doesn't introduce new ones:

#include <iostream>

// Original average function with integer division problem
double calculateAverage_fixed(int a, int b, int c)
{
    return static_cast<double>(a + b + c) / 3.0;  // Fixed: Use floating-point division
}

int main()
{
    // Test the fix with problematic cases
    std::cout << "Testing fixed average function:" << std::endl;
    
    double avg1 = calculateAverage_fixed(1, 2, 2);    // Was 1, should be 1.67
    double avg2 = calculateAverage_fixed(10, 11, 12); // Was 11, should be 11
    double avg3 = calculateAverage_fixed(7, 8, 9);    // Was 8, should be 8
    double avg4 = calculateAverage_fixed(1, 1, 1);    // Should still be 1
    
    std::cout << "Average of 1, 2, 2: " << avg1 << std::endl;
    std::cout << "Average of 10, 11, 12: " << avg2 << std::endl;
    std::cout << "Average of 7, 8, 9: " << avg3 << std::endl;
    std::cout << "Average of 1, 1, 1: " << avg4 << std::endl;
    
    return 0;
}

Output:

Testing fixed average function:
Average of 1, 2, 2: 1.66667
Average of 10, 11, 12: 11
Average of 7, 8, 9: 8
Average of 1, 1, 1: 1

Common debugging strategies

Rubber duck debugging

Explain your code line by line to an inanimate object (like a rubber duck). Often, verbalizing the problem helps you spot the issue.

Divide and conquer

Split your code into smaller parts and test each part individually:

#include <iostream>

// Complex function that might have bugs
int processData(int input)
{
    // Step 1: Validate input
    if (input < 0)
    {
        std::cout << "Debug: Negative input detected" << std::endl;
        return -1;
    }
    
    // Step 2: Transform input
    int doubled = input * 2;
    std::cout << "Debug: Doubled value: " << doubled << std::endl;
    
    // Step 3: Apply formula
    int result = doubled + 10;
    std::cout << "Debug: After adding 10: " << result << std::endl;
    
    return result;
}

int main()
{
    int value = processData(5);
    std::cout << "Final result: " << value << std::endl;
    
    return 0;
}

Output:

Debug: Doubled value: 10
Debug: After adding 10: 20
Final result: 20

Binary search debugging

Comment out half of your code to isolate which half contains the bug:

#include <iostream>

int problematicFunction(int x)
{
    // First half - basic operations
    int step1 = x * 2;
    int step2 = step1 + 5;
    
    // Second half - more complex operations
    // Commenting out this section to test if bug is here
    /*
    int step3 = step2 / 0;  // This would cause a problem
    return step3;
    */
    
    return step2;  // Temporary return for testing
}

int main()
{
    int result = problematicFunction(10);
    std::cout << "Result: " << result << std::endl;
    
    return 0;
}

Output:

Result: 25

Best practices for debugging

1. Keep a debugging journal: Write down what you tried and what happened
2. Use version control: Keep track of changes so you can revert if needed
3. Test edge cases: Try unusual inputs that might break your code
4. Use meaningful variable names: Makes debugging much easier
5. Add temporary debug output: Print intermediate values to understand flow
6. Take breaks: Sometimes stepping away helps you see the problem clearly

Example: Complete debugging session

Let's walk through a complete debugging session:

#include <iostream>

// Original buggy code
/*
int findMax(int arr[], int size)
{
    int max = 0;  // Bug 1: Wrong initialization
    for (int i = 1; i < size; ++i)  // Bug 2: Starting from 1 instead of 0
    {
        if (arr[i] > max)
            max = arr[i];
    }
    return max;
}
*/

// Step-by-step debugging process:

// Version 1: Add debug output
/*
int findMax(int arr[], int size)
{
    int max = 0;
    std::cout << "Debug: Initial max = " << max << std::endl;
    
    for (int i = 1; i < size; ++i)
    {
        std::cout << "Debug: Checking arr[" << i << "] = " << arr[i] << std::endl;
        if (arr[i] > max)
        {
            max = arr[i];
            std::cout << "Debug: New max = " << max << std::endl;
        }
    }
    return max;
}
*/

// Version 2: Fix initialization
/*
int findMax(int arr[], int size)
{
    if (size <= 0) return 0;  // Handle edge case
    
    int max = arr[0];  // Fix: Initialize with first element
    std::cout << "Debug: Initial max = " << max << std::endl;
    
    for (int i = 1; i < size; ++i)
    {
        std::cout << "Debug: Checking arr[" << i << "] = " << arr[i] << std::endl;
        if (arr[i] > max)
        {
            max = arr[i];
            std::cout << "Debug: New max = " << max << std::endl;
        }
    }
    return max;
}
*/

// Final corrected version
int findMax(int arr[], int size)
{
    if (size <= 0) return 0;  // Handle edge case
    
    int max = arr[0];  // Initialize with first element
    
    for (int i = 1; i < size; ++i)  // Start from second element
    {
        if (arr[i] > max)
            max = arr[i];
    }
    return max;
}

int main()
{
    int numbers[] = {3, 1, 4, 1, 5, 9, 2, 6};
    int size = sizeof(numbers) / sizeof(numbers[0]);
    
    int maximum = findMax(numbers, size);
    std::cout << "Maximum value: " << maximum << std::endl;
    
    // Test edge cases
    int empty_size = 0;
    int empty_max = findMax(numbers, empty_size);
    std::cout << "Maximum of empty array: " << empty_max << std::endl;
    
    return 0;
}

Output:

Maximum value: 9
Maximum of empty array: 0

Summary

The debugging process is systematic and methodical:

1. Recognize the problem exists
2. Reproduce the problem consistently
3. Isolate where the problem occurs
4. Form hypotheses about the cause
5. Test your theories
6. Fix the identified issue
7. Verify the fix works

Effective debugging requires patience, systematic thinking, and practice. The more you debug, the better you'll become at quickly identifying common patterns and causes of bugs.

In the next lesson, you'll learn specific strategies and approaches that make debugging more efficient and effective.

Quiz

1. What are the seven steps in the systematic debugging process?
2. Why is it important to reproduce a bug before trying to fix it?
3. What is "rubber duck debugging" and why can it be effective?
4. What should you do after fixing a bug?
5. Why might adding debug output statements help in the debugging process?

Practice exercises

1. Debug this function that's supposed to count positive numbers:

   int countPositive(int arr[], int size)
   {
       int count = 0;
       for (int i = 0; i <= size; ++i)  // Bug here?
       {
           if (arr[i] > 0)
               count++;
       }
       return count;
   }
   

2. Find the logical error in this temperature conversion:

   double celsiusToFahrenheit(double celsius)
   {
       return celsius * 9 / 5 - 32;  // Is this correct?
   }
   

3. Debug this factorial function:

   int factorial(int n)
   {
       if (n <= 1)
           return 1;
       return n * factorial(n + 1);  // What's wrong here?
   }
   

4. Practice the debugging process: Find a piece of code you've written that had a bug, and walk through the seven-step debugging process you would have used to fix it.