Debugging

Classify the observed failure before choosing a tool

Debugging begins with an observation, not a tool. If Python cannot parse the program, it reports a syntax error and identifies a location in the source. For example, if True print("hello") cannot be compiled because the conditional header lacks its required colon. That error is different from a runtime exception: 1 / 0 is valid Python syntax, but executing it raises ZeroDivisionError. The program began running and encountered an operation it could not complete.

A third category is often called a logic or semantic error. The program executes, but its output does not meet the program's intended rule. A function meant to compute an average might accidentally return the sum. Python cannot infer that the programmer wanted a different calculation, so no traceback is guaranteed. The debugging evidence must instead compare an expected result with the actual result and inspect the steps between them. Keep this classification practical: a single defect can expose more than one symptom, but naming the first observable kind of problem helps choose the next check.

Treat a traceback as a route through the failing call

When an exception is unhandled, Python prints a traceback. Read it from the bottom first: the final line names the exception type and usually supplies its message. Then move upward through the listed calls to see how execution reached that line. A file name and line number identify source locations; they are clues to inspect, not a substitute for understanding the values and assumptions at that point.

Suppose a function divides a total by len(values). Calling it with an empty list produces ZeroDivisionError: division by zero. The immediate expression failed, but the useful debugging question is also why an empty list was allowed to reach the function. Check the call site, the input, and the function's contract. Do not respond by broadly hiding the exception; designing try/except behavior is the separate Exceptions lesson. Here, use the traceback to form a specific hypothesis, then make the smallest safe observation that could confirm or reject it.

Use a controlled investigation loop

A reliable loop is: reproduce the behavior, state one hypothesis, gather one relevant observation, make a focused change, and run the same case again. Reproduction matters because a one-off symptom is hard to compare after a change. If the full program is noisy, reduce it to the smallest program and input that still displays the behavior. Reduction is not merely shortening code; it preserves the behavior you are trying to explain while removing unrelated paths. Keep a record of the exact input, command, and observed output, because an investigation is much harder to repeat when its starting conditions are guessed later. A written observation is useful only when it is specific enough that someone else could check it.

For a small program, an intentional print() can expose an intermediate value, a branch decision, or the size of a collection. Print labels as well as values so output remains interpretable: print(f"count={len(values)} total={total}"). Remove or replace temporary inspection after the question is answered, since debugging output can obscure normal output. For a failure involving repeated calls or nested functions, pdb is Python's standard-library debugger. It can pause at a breakpoint, step through source lines, inspect stack frames, list source, and evaluate expressions in the selected frame. That makes it useful when another print statement would not reveal which call or frame contains the unexpected state.

A fix is not finished when an error message disappears. Re-run the original failing case and at least one nearby case that should still work. If changing a denominator check makes the empty-list case clear but breaks ordinary lists, the investigation has uncovered a new defect rather than completed the old one. This lesson focuses on diagnosis; systematic test-suite design belongs to Basic Testing.