9 rules for debugging anything (Book Review)

Code flows effortlessly from your nimble fingers, like fine cloth from a loom. Your face is serene, focused, content. Suddenly, a wrinkle appears in your brow, breaking that pleasant mask of serenity. The frown deepens. “That can’t be right…” What happened? A bug! A hairy bug lurks fiendishly somewhere in that elegant tapestry of code love. How did the bug slip past you? You were so careful! A frustrated hour passes, then two. You comb through each strand of code, retrace your steps through the intricate lattice of if, when, and for…

We sink so much time into the deep pit that is debugging. Yet for all the time we spend on it, there is surprisingly little literature written on the subject. A notable exception is Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems, by David J Agans.

Table of Contents

I picked up Mr. Agans’ Debugging book a few years ago because I wanted to hone my debugging skills, it was on sale, and — don’t let that long title fool you — it’s short. What wisdom will you unearth inside its 206 pages?

The nine rules of debugging

Debugging doesn’t expose you to specific debugging tools like the ones you’d find in Visual Studio. It’s more about adopting a debugging mindset. Once you’ve absorbed that mindset, you can debug anything, from the leak in your kitchen sink to the memory leak in your web app. To that end, the author provides us with “9 rules” to turn us into crack shot debuggers. Here is a brief synopsis of each of the 9 rules.

1. Understand the System

First of all, you have to understand the system. This is arguably the hardest part, and likely the reason why debugging is so difficult and onerous for most of us. There’s so many systems, and so many intricacies surrounding them, that we don’t really know how they do what they do.

Nonetheless, when faced with an inexplicable bug, it’s time to break out the specs and read them with fresh eyes. Don’t just assume you know how the system functions, really know. Draw it out on a whiteboard. Test your assumptions with some unit tests and maybe a quick spike.

2. Make it Fail

Two words: “repro steps.” If you can’t make it fail and reproduce the bug, you’re just throwing darts in the dark.

3. Quit Thinking and Look

You can close your eyes, lean back in your chair, and brainstorm possible sources of the bug all day long. Maybe one of those ideas is correct. But you won’t really know until you stop thinking and start exploring. Pull out your proverbial stick and start poking around in the system. See what breaks, who yells.

4. Divide and Conquer

Start eliminating possible sources of the bug, ideally via a binary search algorithm. Eliminate half the system as a bug-harboring candidate. Then eliminate the next half, and the next half, until the bug is staring at you sheepishly with its creepy bug tail between its legs.

5. Change One Thing at a Time

Don’t change a million things at once. Change one variable and retest. Did anything change? Put it back the way you found it; try another one. This systematic method seems tedious, but you often save time in the long run.

6. Keep an Audit Trail

Write down everything you’ve tried in search of the bug. This will help prevent you from trying the same thing twice, especially in drawn out debugging sessions, as well as serve as a nice debugging log in case you have to turn over your bug hunting hat to someone else.

7. Check the Plug

Sometimes the most mind boggling bugs can be traced back to the simplest of causes — someone unplugged the cable. Take nothing for granted. Trace your way up the tech stack, from the lowly cable on up to the highest level 7 abstraction. Where are things breaking down?

8. Get a Fresh View

You’ve been banging your head on keyboard for hours while the bug just points at you with its fancy walking cane and laughs ironically, then tips its top hat derisively. You’re frustrated, bleary eyed, seeing things that aren’t really there. It’s time to step away from the computer. Take a walk. Talk to a buddy. Describe the problem, whiteboard it. Maybe talking about the issue will trigger something new to try, or your buddy will catch something you missed.

9. If You Didn’t Fix It, It Ain’t Fixed

Hey look, the bug mysteriously disappeared! That’s great, now I can go back to work. Well… We’ve all been there. Usually the bug comes back, when you least expect it, and with terrible timing. If you didn’t fix it, you didn’t fix it.

Why is that bug wearing a top hat?

important stakeholder

Conclusion: To debug faster, debug slower

Yes, I recommend Mr. Agans’ book. It’s full of good stories from the trenches of hardware debugging that make the points nicely. If nothing else, it will help you slow down and take debugging more seriously, which paradoxically, will make you a faster debugger.