The Gentle Art of Debugging

There's a moment in every long debugging session where you stop being angry at the computer and start being curious about it. Everything good happens after that moment.

The machine is never wrong

This is the hardest lesson and the most freeing one. The program is doing exactly what somebody told it to do. Debugging is archaeology: you're not fixing the machine, you're discovering what you actually asked for.

My four questions

Before I touch a debugger, I write down answers to these:

1. What did I expect to happen?
2. What actually happened?
3. What is the smallest input that shows the difference?
4. When did this last work?

Question 3 does most of the heavy lifting. Shrinking the reproduction is the debugging — by the time the repro is minimal, the bug is usually obvious.

Bisection is a superpower

git bisect gets all the press, but the mindset generalizes to everything:

git bisect start
git bisect bad HEAD
git bisect good v2.1.0
# git checks out the midpoint; test it, then:
git bisect good   # or bad — repeat until it names the commit

Half the search space disappears with every test. Twenty commits become five tests. A thousand lines of config become ten checks. Binary search doesn't care what it's searching.

Rubber ducks work because you don't

The duck isn't magic. Explaining forces you to serialize your assumptions, and the broken one usually can't survive being said out loud. Write the bug report you would send someone, and you'll rarely need to send it.

Be gentle with the code. It was written by someone doing their best with what they knew — and statistically, that someone was you, three months ago.