Debugging: finding bugs systematically

Why poking at random fails

Typical beginner behaviour: change things at random, restart, hope. Occasionally it works — which is the worst outcome, because the cause remains unknown and will return.

Debugging isn't luck, it's a procedure. It can be learned, and it works nearly always.

The procedure

1. Reproduce it. Until you can trigger the bug at will, there's nothing to fix. Find the exact steps: which data, which sequence of actions.

If it doesn't reproduce reliably, that's a separate case, covered below.

2. Read the whole message. Not the first line. It usually contains the error type, the location and a call chain. Half of all problems resolve at this step.

Read the chain from the bottom up, looking for the first line belonging to your code rather than a library.

3. State what you expected. In writing, one sentence: "expected a list of three records, got an empty one". That forces the problem into focus and often suggests the answer immediately.

4. Narrow the area. The main technique. The task isn't to find the bug but to find the half of the code where it definitely isn't.

Methods:

• bisect: check whether execution reaches the midpoint;
• reduce the input to the minimum that still fails;
• remove half the functionality and see whether the problem remains.

5. Verify your assumptions. The bug is almost always where you're certain. "The data definitely arrives here" — check that it does. "This function is definitely called" — confirm it.

Tools

Printing to the console. Nothing shameful, always works. Print a label along with the value, or five prints in you'll be lost.

A debugger. Lets you halt execution and inspect every value at once. An hour to learn, weeks saved. Beginners fear it needlessly.

Logs. For what happens on a server or happens rarely.

Type checking and a linter. Some bugs are caught before anything runs.

Intermittent failures

The nastiest case. The usual causes:

• Execution order. Something hasn't finished before its result is needed.
• Shared state. Data left over from a previous action.
• Caching. Browser, build, platform. Check with a full reload.
• Different data. Some records have an empty field and some don't.

A technique: log with precise timestamps and look at what happens immediately before the failure. Often the order of events differs.

When you're stuck

The half-hour rule. Thirty minutes without progress means change approach or ask.

Explain it to someone. The classic: talking it through, you find the answer midway. It works even with someone who doesn't understand the subject.

Step away. Fifteen minutes' break often achieves more than two hours of persistence.

Check the obvious. Are you editing the right file? Did you restart the right server? Is the file saved? Absurd, but a regular cause.

After the fix

Ask two questions: why did this happen and how do I catch it earlier next time?

If the bug was subtle, write a test that reproduces it. That's the only way to guarantee it doesn't come back.