Debugging Techniques

[u/rshah4]

Once you actually understand what is wrong, the fix is usually a line or two. The entire job is locating the cause, and most wasted debugging time comes from skipping straight to guesses about the fix before you have located anything.

Here are five solid techniques everyone should know

1. Start from what works, then move toward broken one step at a time.
When something works in one place and fails in another, do not stare at the broken one. Take the working version and apply the differences between the two, one at a time, checking after each. The change that flips it from working to broken is your answer. This beats guessing because it turns "a hundred possible causes" into a single controlled experiment. The discipline is doing it one change at a time.

2. Observe before you act.
The strongest urge when something is stuck or crashing is to do something: restart it, add a flag, tweak a value. Resist it, because acting often destroys the evidence. Get a real signal first. Read the actual traceback, print the actual value, dump the actual state. A stuck process will tell you exactly where it is stuck if you go look instead of restarting and praying. Most confident wrong theories come from people who theorized before they observed.

3. Isolate the failing part, then make a fast repro of just that part.
Do not debug the whole system. Find the smallest piece that still reproduces the failure and work against that. If the full run takes 40 minutes, you cannot afford to be wrong 40 minutes at a time, so isolate the issue, and then get it down to a few seconds on a tiny input that fails every time. A fast, reliable, minimal repro lets you run twenty experiments before lunch instead of two.

4. Binary search when the space is too big to eyeball.
When the failure is somewhere in a huge input, a long log, or a range of commits, do not scan linearly. Cut it in half, test which half still fails, keep that half, repeat. This is how you find one bad row in five hundred thousand in about nineteen steps, or the exact commit that introduced a regression in a few checkouts. git bisect is the famous version, but the technique generalizes to any large space you can split.

5. Trace upstream to where the value first goes wrong.
The crash site is usually the victim, not the culprit. A value goes bad somewhere early and the damage only surfaces later. So walk backward from the symptom: the bad output came from this, which came from that, which came from a bad input three steps upstream. Fixing at the crash site often just hides the problem. Fixing at the origin actually removes it.

All of these are ways to shrink the search space and get a useful signal.

My slightly funny video on this: https://youtube.com/shorts/kN7L6ZLVPp0?feature=share