Debugging with printf

The Philosophy of Print Debugging

A program can be thought of as a black box: you provide input, it performs some processing, and you get an output (the IPO model). When the output is wrong, the problem is hidden inside the "processing" step. Print debugging is the art of inserting small windows into that black box to observe the internal state as it executes.

The following video provides an excellent introduction to this concept and demonstrates how to apply it to a real C program to find a bug.

As you saw, by printing the state of key variables within the loop, the programmer could visualize the program's execution and quickly spot where the logic went wrong.

Mastering the Tool: A printf Refresher

To use printf effectively for debugging, you need to be comfortable with its syntax, especially the format specifiers that tell it how to interpret and print different data types. Mismatching a format specifier and a variable's type is a classic C bug that can lead to garbage output or crashes.

Let's do a quick but thorough review of the printf function.

int user_id = 101;
double score = 95.7;
char *username = "testuser";

The "Art" of Strategic printf Placement

Knowing printf's syntax is the first step. The real skill is in knowing what to print and where. Your experience with debugging in other languages will serve you well here. The goal is to formulate a hypothesis about the bug and use printf to test it.

The following article, while not C-specific, outlines several classic bug patterns that print debugging is exceptionally good at revealing.

Here are some key strategies to adopt:

• Trace Execution Flow: Print a message at the start of functions to see if, when, and in what order they are called.

  void process_data(int *data) {
      printf("DEBUG: Entering process_data()\n");
      // ...
  }
  

• Inspect Variable State: Print variable values at critical points: before and after modification, inside loops, and before they are used in a condition.

  for (int i = 0; i < len; i++) {
      printf("DEBUG: Before: array[%d] = %d\n", i, array[i]);
      array[i] = array[i] * 2;
      printf("DEBUG: After:  array[%d] = %d\n", i, array[i]);
  }
  

• Check Conditional Branches: If you're not sure which path your code is taking, a printf in each branch will tell you instantly.

  if (x > THRESHOLD) {
      printf("DEBUG: x > THRESHOLD was true.\n");
      // ...
  } else {
      printf("DEBUG: x > THRESHOLD was false.\n");
      // ...
  }
  

• Reveal "Invisible" Characters: When dealing with strings, especially user input, whitespace can cause baffling issues. Printing strings with delimiters makes these characters visible.

  printf("DEBUG: Input username was '[%s]'\n", username);
  

A More Professional Approach to Print Debugging

A major downside of littering your code with printf statements is that you have to manually remove them later. This is tedious and error-prone. A more professional approach uses the C preprocessor to create debug messages that can be enabled or disabled with a single switch at compile time.

The core idea is to wrap your debug print in a macro like this:

// In a header file, e.g., debug.h
#ifdef DEBUG
    // The `##__VA_ARGS__` handles cases where you have no extra arguments.
    // We use fprintf to stderr so debug messages don't mix with normal output.
    #define DEBUG_LOG(fmt, ...) fprintf(stderr, "DEBUG: %s:%d:%s(): " fmt, \
        __FILE__, __LINE__, __func__, ##__VA_ARGS__)
#else
    // If DEBUG is not defined, the macro expands to nothing.
    #define DEBUG_LOG(fmt, ...)
#endif

With this, you can sprinkle DEBUG_LOG("Value of x is %d\n", x); throughout your code. When you compile with gcc -DDEBUG my_program.c, the messages will be printed. When you compile normally with gcc my_program.c, the preprocessor removes them completely, resulting in zero performance overhead in your final release build. The special identifiers __FILE__, __LINE__, and __func__ automatically add valuable context to your messages.

Conclusion

You now have a powerful, practical technique for diagnosing logical errors in your C code. While modern debuggers (which we'll cover later) are indispensable, print debugging is fast, simple, and forces you to think critically about your code's execution flow.

Key Takeaways:

• printf debugging is used to find logical errors by making program flow and variable states visible.
• Mastery of printf format specifiers is essential to avoid creating new bugs while trying to find old ones.
• Strategic placement is key: trace function calls, inspect variable states before and after changes, and verify control flow through conditionals.
• For professional code, wrap debug prints in preprocessor macros that can be enabled or disabled at compile time.

In our next lesson, we'll dive deeper into what makes this possible. We will fully explore C preprocessor directives, covering file inclusion (#include), conditional compilation (#ifdef), and creating powerful macros (#define).

Practice Exercises

The only way to get good at debugging is to do it. The following programs all contain logical bugs. Your task is to use printf debugging to find and fix them. For each exercise, compile and run the buggy code first to see the incorrect behavior. Then, add printf statements to diagnose the problem.

1. Faulty Factorial: This function is meant to calculate the factorial of a number using recursion, but it produces incorrect results. Use printf to trace the value of n at the entry and exit of each recursive call to understand the flow and find the error.

   #include <stdio.h>
   
   // Should calculate n! (e.g., 5! = 120)
   int factorial(int n) {
       if (n == 1) {
           return 1;
       }
       return n + factorial(n - 1); // Bug is here!
   }
   
   int main() {
       int num = 5;
       printf("Factorial of %d is %d\n", num, factorial(num));
       return 0;
   }
   

2. Off-by-One Array Sum: This function is supposed to sum all elements in an array, but it consistently returns the wrong total. Print the loop index i and the value of sum in each iteration to see where the calculation goes wrong.

   #include <stdio.h>
   
   int sum_array(int arr[], int size) {
       int sum = 0;
       for (int i = 1; i <= size; i++) { // Bug is here!
           sum += arr[i];
       }
       return sum;
   }
   
   int main() {
       int my_array[] = {10, 20, 30, 40, 50};
       int size = sizeof(my_array) / sizeof(my_array[0]);
       printf("Sum should be 150, but is: %d\n", sum_array(my_array, size));
       return 0;
   }
   

3. String Reversal Bug: This function attempts to reverse a string in place, but it corrupts the string. Use printf to display the start and end pointers/indices and the characters they point to before and after each swap.

c
#include <stdio.h>
#include <string.h>

void reverse_string(char *str) {
    int start = 0;
    int end = strlen(str); // Bug is here!
    char temp;
    while (start < end) {
        temp = str[start];
        str[start] = str[end];
        str[end] = temp;
        start++;
        end--;
    }
}

int main() {
    char my_string[] = "hello";
    reverse_string(my_string);
    printf("Reversed string: %s\n", my_string);
    return 0;
}
```

4. Incorrect Grade Calculation: This function is supposed to return a letter grade based on a score. However, because of the if-else if order, it returns incorrect grades for many scores. Add a printf inside each conditional block to see which branch is actually being executed for different test scores (e.g., 95, 75, 55).
```c
#include <stdio.h>

char get_grade(int score) {
    if (score > 60) { // Bug is here! Should check highest grades first.
        return 'D';
    } else if (score > 70) {
        return 'C';
    } else if (score > 80) {
        return 'B';
    } else if (score > 90) {
        return 'A';
    } else {
        return 'F';
    }
}

int main() {
    int test_score = 85; // Should be 'B', but what does it print?
    printf("Score %d gets grade %c\n", test_score, get_grade(test_score));
    return 0;
}
```

5. Pointer Confusion: This function tries to swap two integers, but it fails. This is a classic C problem related to pass-by-value. Use printf to print the addresses of a and b inside main and the addresses of x and y inside swap. This will reveal that swap is operating on copies, not the original variables.
```c
#include <stdio.h>

void swap(int x, int y) { // Bug is here! This should take pointers.
    int temp = x;
    x = y;
    y = temp;
    printf("Inside swap: x = %d, y = %d\n", x, y);
}

int main() {
    int a = 10;
    int b = 20;
    printf("Before swap: a = %d, b = %d\n", a, b);
    swap(a, b);
    printf("After swap: a = %d, b = %d\n", a, b);
    return 0;
}
```