Systematic Debugging

Before this

• JavaScript Fundamentals — Types, scope, coercion, `this` — the base layer everything else in this track sits on.

Why this exists

Staring at code that "should work" and reading it over and over rarely finds the bug — you already believe it's correct, which is exactly why you wrote it that way. Systematic debugging replaces belief with evidence: reproduce the failure reliably, narrow down where it starts, form a specific hypothesis, and test that hypothesis directly instead of guessing.

The mental model

Debugging is binary search over a space of possible causes, not a search over code. Each check you run should roughly halve the remaining space of "where could this be" — not add another random print statement in the same function you've already stared at ten times.

How it works

The mechanism

The loop is deliberate: reproduce, narrow, hypothesise, test — and if the hypothesis is wrong, you form a new one with the information you just gained, rather than starting over. Once a fix is applied, you re-run the ORIGINAL reproduction, not a new simplified case, because that's the only proof the actual reported bug is gone.

flowchart TD
  A[Reproduce reliably] --> B[Bisect: narrow the location]
  B --> C[Form a specific hypothesis]
  C --> D{Test the hypothesis}
  D -->|Confirmed| E[Fix at the root cause]
  D -->|Refuted| C
  E --> F[Re-run the original reproduction]
  F -->|Still fails| B
  F -->|Passes| G[Done]

What people get wrong

Adding more log statements everywhere will eventually reveal the bug.

Untargeted logging produces so much noise that the signal gets lost — a single, well-placed check at the midpoint of the suspect range is more informative than fifty scattered prints. Shotgun debugging feels productive because you're doing something, but it doesn't shrink the hypothesis space the way a targeted binary search does.

If the fix makes the error message go away, the bug is fixed.

The error message going away often just means the symptom moved somewhere quieter — the actual root cause, like a null value from an upstream function, may still exist and surface differently later. Fixing symptoms instead of causes is why the same underlying bug reappears in a slightly different form a few weeks later, wasting the debugging effort a second time.

Debugging is a talent some people have and others don't.

Debugging is a method — reproduce, bisect, hypothesise, verify — that improves with deliberate practice like any other skill, not an innate trait. Treating it as talent discourages people from learning the systematic process, and encourages randomly poking at code instead, which is genuinely the slower approach regardless of experience.

When not to use it

The bug is a crash with a full stack trace pointing at an exact line.

Skip the bisection step — you already have the location. Go straight to forming a hypothesis about why that line fails and checking the values involved.

The failure only happens in production and cannot be reproduced locally at all.

Reach for observability data — logs, traces, metrics — from the actual failing request rather than trying to guess a local reproduction; see `logging-observability`.

Terms

Reproduction case

— The smallest, most reliable set of steps known to trigger a bug, used as the ground truth for whether a fix actually worked.

Bisection

— Repeatedly halving the space of possible causes — in code, in commit history, or in a data pipeline — rather than checking candidates one at a time from the start.

Root cause

— The earliest point in a chain of events where something went wrong, as distinct from the point where the failure became visible.

Heisenbug

— A bug that seems to disappear or change behaviour when you try to observe it, typically caused by timing sensitivity that debugging tools themselves perturb.

In an interview

Connected ideas

• Logging & Observability — Structured logs, metrics, traces — being able to answer 'what happened?' at 3am.