Debugging systematically

Look inside the running code

Labeled prints are the fastest tool. An f-string with = prints both the expression and its value, so you never wonder which number is which:

price, qty = "19.50", 3
print(f"{price=} {qty=} {type(price)=}")

Logging is print for code that stays, like a ship's log. Messages carry a level, from DEBUG up to ERROR, so you can switch the detailed ones on only while you investigate:

import logging, sys
logging.basicConfig(stream=sys.stdout, level=logging.INFO, format="%(levelname)s %(message)s", force=True)
log = logging.getLogger("orders")
log.debug("this is hidden at INFO level")
log.info("processing order %s", 42)
log.warning("order %s has no email", 42)

A debugger pauses the program so you can look around, like pausing a film to study one frame. Put breakpoint() on a line and run the script in a terminal. Python stops there, and you can type commands:

p total        print a variable
n              run the next line
s              step into a function call
c              continue until the next breakpoint
q              quit

Code editors such as VS Code give you the same thing with buttons: click beside a line to set a breakpoint, then step through and watch variables update.

Bisect: find the change that broke it

"It worked last week." Somewhere among the last 200 commits, something broke. Think of an old string of lights with one bad bulb. You wouldn't test them in order. You'd check the middle first.

Checking all 200 commits is slow. Instead, test the commit in the middle. If it's broken, the bad change is in the first half. If it works, the change is in the second half. That's binary search again: 200 commits take about 8 checks. Git does this for you with git bisect:

git bisect start
git bisect bad              # the current commit is broken
git bisect good v1.4        # this older version worked
# git checks out a commit in the middle; you test it, then type:
git bisect good             # or: git bisect bad
# ...repeat until git names the first bad commit
git bisect reset

Bugs you'll meet again and again

The same few mistakes turn up in every language and on every team, so they're worth learning to recognize:

That last one surprises everyone once. It's like a shared notepad left on a table, which still has the last person's notes on it:

def add_tag(tag, tags=[]):        # the default list is made ONCE, when def runs
    tags.append(tag)
    return tags

print(add_tag("sale"))
print(add_tag("new"))             # the "empty" default remembers "sale"!

def add_tag_fixed(tag, tags=None):
    if tags is None:
        tags = []                 # a fresh list on every call
    tags.append(tag)
    return tags

print(add_tag_fixed("sale"), add_tag_fixed("new"))

When you're stuck, explain the code out loud, line by line, to a colleague or even a rubber duck. You'll often hear the mistake as you say it. If you ask a person or an AI for help, give them the full error, the smallest code that shows it, what you expected and what you've tried.

Fix the cause, not the crash

A painkiller doesn't mend a broken bone. The line where a program crashes often isn't where the bug is. It's where the bad data finally caused trouble.

Say total_price crashes because price is None. Adding if price is None: price = 0 there makes the crash go away. Now you're silently charging nothing for an item, and you've turned a loud bug into a quiet one. The real question is why price was None. Follow it backward: who called this function, and where did they get that value? Fix it at the place where the wrong value came in.

Changing things at random

Everyone does this when tired: change a line, run it, change another. Sometimes the error goes away, and you never learn why. Then either it comes back, or one of your random changes breaks something else.

So change one thing at a time, and predict what will happen before you run it. If the result surprises you, your idea of the code is wrong, and that surprise is the most useful information you'll get all day. Take a short break if you're stuck, and try explaining the problem aloud, even to nobody. People find the answer mid-sentence surprisingly often.

Finish the job with a test

When you've found the bug, write a test that fails because of it. Then fix it and watch the test pass. It takes a few minutes, and it does two things. It proves that you fixed the real problem, not a look-alike. And it stops this bug from ever coming back quietly. A fix that "obviously works" has a way of returning six months later.