A Practical Attitude for Debugging
Debugging is as much about mindset as it is about tools. A recent zine project distilled that mindset into a short manifesto, and the principles hold up well beyond the zine's pages. Here’s a breakdown of those ideas, with some practical context.
Inspect First, Fix Later
The urge to patch a bug the moment you see it is strong. In a production incident, that urgency is justified—you mitigate first and investigate afterward. But in everyday development, jumping straight to a fix or a workaround tends to backfire. Leaving the bug in place long enough to understand exactly what went wrong is usually faster and more effective. Hasty fixes without a root cause often leave you more confused than when you started.
Stuck Is a State, Not a Verdict
Debugging sessions can feel endless. When progress stalls, it’s easy to spiral into demoralization. A useful antidote is remembering that you have solved bugs before, and this one will likely join that list. The feeling of being permanently stuck is temporary, even when it doesn’t feel that way.
Question Everything, Including the OS
Bugs can come from sources you’d never suspect. A first attempt at a Mac OS program once turned out to be broken not by user error, but by a genuine kernel bug. Normally, the operating system is not at fault, but it happens. The same goes for popular libraries, official documentation, and even the smartest coworkers. Assume nothing is infallible.
But Start With Your Own Code
That said, the inverse is far more common. In the vast majority of cases—easily 95% for most developers—the problem is a silly mistake you made. It’s tempting to blame external systems, but the logical first step is always to scrutinize your own logic and assumptions. Look inward before you point outward.
Collaboration Accelerates Debugging
Asking for help is one of the best ways to debug, and it’s also a great way to learn. A second set of eyes brings a different toolkit and perspective. That collaboration often surfaces useful knowledge you wouldn’t have sought out on your own: how to use gdb to inspect memory, how CORS actually works, or a recollection that a similar breakage occurred before in a specific way.
There Is Always a Cause
When things feel like they’re breaking randomly, that perception is wrong. There is always a reason, even if the reason is an elusive hardware fault. The universe isn’t out to get you; it’s just being stubborn about revealing the cause.
Invest in Your Toolkit
To fix a bug, you need information about what the program is doing. That often means learning a new tool—something like tcpdump or strace—to get the visibility you need. Sometimes the right tool isn’t off the shelf, and you have to build your own: improving a test suite, adding better pretty-printing, or writing a custom diagnostic script. A stronger toolkit makes every future bug easier to crack.
Treat Bugs as a Learning Opportunity
Debugging is an investment in future knowledge. When something breaks, it’s usually because a mental model is wrong somewhere. Fixing the code is good; fixing the model is better. Not every bug feels like an adventure—a stubborn off-by-one error rarely does—but stepping back to see what a bug taught you turns even the most tedious session into something worthwhile.
