Advanced Debugging

By the end of this lesson you'll be able to read a C++ compiler error and fix the real cause, add assertions and print/cerr traces, drive gdb to pause and inspect a running program, and switch on AddressSanitizer and UBSan to catch memory bugs and undefined behaviour automatically.

1. Reading Errors & a Worked Fix

Bugs come in two waves. Compile errors stop the build, and the rule is simple: fix the first error first — later errors are usually knock-on noise from the same mistake. Read the file:line at the start, then the short phrase after error:. The second wave is runtime bugs: the code builds but does the wrong thing. The single most common one is the off-by-one — looping one step too far. Study this worked example: a buggy average function, and right below it the commented fix.

#include <iostream>
#include <vector>
using namespace std;

// A program that should print the average of some scores.
// It has a classic off-by-one bug. The FIX is shown below it.

double averageBuggy(const vector<int>& scores) {
    int sum = 0;
    // 🐞 BUG: <= reads scores[scores.size()], one past the end.
    // That index does not exist -> undefined behaviour (garbage / crash).
    for (size_t i = 0; i <= scores.size(); i++) {
        sum += scores[i];
    }
    return static_cast<double
...

2. Assertions & Print/cerr Debugging

An assert(condition) aborts the program with a message the moment condition is false. It does two jobs at once: it documents an assumption and it checks it, so a broken assumption trips the alarm right where it happens instead of corrupting data and crashing far away. Print debugging is the other workhorse — but send it to cerr, the error stream, not cout. cerr is unbuffered, so the line appears immediately even if the program crashes on the very next statement; cout is buffered and can swallow your last message.

#include <iostream>
#include <cassert>
#include <vector>
using namespace std;

// assert(cond) aborts with a message if cond is FALSE. It documents
// an assumption AND checks it. (Stripped out in release via -DNDEBUG.)

int factorial(int n) {
    assert(n >= 0 && "factorial needs a non-negative n"); // precondition
    int result = 1;
    for (int i = 2; i <= n; i++) {
        result *= i;
        // cerr is the ERROR stream: unbuffered, so it prints even if we
        // crash next line. Great
...

Now you try. The loop below should print all four names, but it walks one index too far — the same off-by-one from the worked example. Replace the ___ with the correct comparison and run it.

#include <iostream>
#include <vector>
using namespace std;

int main() {
    // 🎯 YOUR TURN — this loop should print all 4 names, but it
    // crashes / prints garbage on the last step. Find and FIX the bug.

    vector<string> names = {"Ada", "Bjarne", "Grace", "Linus"};

    // 👉 Replace ___ with the correct comparison so i never reaches
    //    names.size() (the first index that does NOT exist).
    for (size_t i = 0; i ___ names.size(); i++) {   // 👉 use  <  not  <=
        cout << i <
...

One more. This function divides by price, which blows up to inf/nan when the price is zero. Add a guard so the second call returns 0 safely instead of dividing by zero.

#include <iostream>
using namespace std;

// This should report a discount as a percentage of the price.
double discountPercent(double saved, double price) {
    // 🐞 BUG: if price is 0 we divide by zero (result is inf / nan).
    // 👉 Add a guard that returns 0.0 when price is 0, THEN do the maths.
    ___                                   // 👉 if (price == 0) return 0.0;
    return saved / price * 100.0;
}

int main() {
    // 🎯 YOUR TURN — fix discountPercent above so the 2nd call is safe
...

3. Driving gdb: Pause and Inspect

When prints start multiplying, switch to a real debugger. gdb (the GNU Debugger; lldb is the equivalent on macOS) lets you pause a program, read any variable, and step through line by line. First compile with debug info and no optimisation — -g adds the symbols the debugger needs, and -O0 stops the optimiser from reordering code or deleting variables you want to watch. Then it's a small set of commands you'll use constantly:

g++ -g -O0 program.cpp -o program   # compile with debug info, no optimisation
gdb ./program                       # start the debugger

break main          # (b) pause at the start of main
break 42            # pause at line 42
run                 # (r) start the program; stops at the first breakpoint
next                # (n) run the next line, stepping OVER function calls
step                # (s) run the next line, stepping INTO a function call
print scores        # (p) show a variable's current value
print scores[i]     # inspect any expression
backtrace           # (bt) show the call stack — how you got here
continue            # (c) resume until the next breakpoint or the end
quit                # (q) leave gdb

4. Sanitizers & Build Types

Sanitizers are the closest thing C++ has to a superpower. You add one compiler flag, run your program normally, and it reports the exact file and line of a memory bug or undefined behaviour. AddressSanitizer (-fsanitize=address) catches use-after-free, buffer overflow, and double free. UBSan (-fsanitize=undefined) catches undefined behaviour such as signed integer overflow and bad casts. You can switch both on together:

# Build with BOTH AddressSanitizer and UBSan, plus debug info:
g++ -g -O1 -fsanitize=address,undefined program.cpp -o program
./program           # just run it — a bug prints an exact, readable report

# Example ASan report for a buffer overflow:
#   ERROR: AddressSanitizer: heap-buffer-overflow ...
#   READ of size 4 at 0x... thread T0
#       #0 0x... in averageBuggy(...) program.cpp:11
#                                                  ^ the exact line!

Debug vs release builds matter here. A debug build uses -g -O0 (and leaves assert on) so tools can see everything — this is what you develop and test with. A release build uses -O2 -DNDEBUG: the optimiser makes it fast and -DNDEBUG strips out every assert. Ship the release build, but never test only in release — you'd be running code your tools can't see into.

#include <iostream>
#include <cassert>
#include <vector>
using namespace std;

// 🎯 MINI-CHALLENGE: a safe sum function with assertions + a debug trace
//
// 1. Write  int sumRange(const vector<int>& v, size_t start, size_t end)
//    that returns v[start] + ... + v[end-1].
// 2. assert that start <= end AND end <= v.size()  (your preconditions).
// 3. Inside the loop, print a debug line to cerr showing i and the
//    running total (so you can trace it without a debugger).
// 4. In main, call 
...