Published: August 05, 2022 • Updated: April 01, 2023 • 8 min read
This is a list of all the best debugging tips I’ve picked up over the years. It’s inspired by ‘All my best programming tips’ by Jason Swett. That is a great post and you should read it.
As Jason observed, some of these might seem obvious, yet we forget them when it counts. Debugging is hard. You have to bring every tool you have to the job.
I’ve divided this list into three sections: things to do before you start debugging, during debugging, and after the bug is fixed.
If you remember one tip in this list, it should be this: prioritize pair programming for bugfixes. You’ll fix the bug faster, learn (and teach) more, and strengthen your team all at once. It’s the highest-bandwidth debugging technique I know.
Pairing can be tough. Sharing a dev environment remotely requires great tools. Resolving disagreements or experience gaps takes finesse. Constant conversation can tax. These are real, yet solvable problems.
When pairing works, you get combined years of experience, the diversity of opinions that each person brings, and even possibly, some fun.
If you can’t pair, use the Rubber Duck technique.
Humans think faster than they can talk. Slow your thinking down to the speed of speech, and bad ideas have nowhere to hide.
As an aside, Rubber Duck debugging often gives me a surprising morale boost. I feel a little less alone even when talking to an object.
I start debugging with a summary of what I know, as a sentence:
“We’re seeing a bug on the homepage where the user’s message count isn’t updating when it changes.”
Speaking a sentence like that aloud can surface some great questions, such as:
Start answering these, and you’re moving forward.
Stay focused. Don’t get sidetracked. If something’s wrong with your text editor, or you need to update your browser, or there’s an error in your server log that precedes the bug, make a note and fix it later.
Sharpening the saw is great, and if a tweak improves your current situation, consider it. Just don’t let adjustments distract from the task at hand. There are endless things that could be improved, and irrelevant improvements can give a false sense of progress and create new problems.
This tip is crucial when you’re pair programming. With two people there’s double the temptation to embark on pointless, morale-crushing side quests (“this warning is distracting; let’s update npm”).
To fix a bug, you pretty much have to be able to reproduce it. On rare occasions, you can’t in a reasonable amount of time, but you must try.
Reproducing the bug proves that you understand it and lets you test your solution as many times as needed. Almost every time I’ve given up on reproducing the bug, my solution ended up not fixing it for the long term.
Make the bug easy to reproduce, again and again.
Does the bug happen when a certain record is deleted? Write a little script that duplicates that record ten times, so you can focus on observing the deletion.
Is the bug only visible for a millisecond in the middle of a page reload? Throttle your network settings so that you can see it at human speed.
Perhaps the bug reporter spent a half-hour getting into some state where they
found the bug; that doesn’t mean you have to. Automate the reproduction steps
however you can so that you don’t waste energy setting it up. Fake a timestamp!
Comment authentication out! Change a giant
if statement to
true! There are
no rules and if it works, do it.
Before testing anything, from your proposed solution or just an experiment, make a prediction. What do you think will happen?
Making a prediction forces you to take a stand on the bug. That stand gives you something real— a predication that was either right or wrong— to consider.
When you learn something that you know is true, write it down.
Something that can kill a debugging session is backsliding. You’re zeroing in on the bug in the frontend, you lose focus, or bring in an observer who isn’t up to speed, and suddenly you’re asking “could this be a database issue?”
There are a lot of moving pieces in technology; to make progress, you have to be able to rule things out. If you’ve already figured out for sure that the issue is on the frontend, write down why that’s true and don’t go backward.
It’s okay to revisit the assertion, but you shouldn’t go around it.
Learn to smartly print values so you can make and verify your predictions.
Rubyists call this “Puts-Driven-Development” because you’re printing with the
puts method. Learn how to print out the right information. Use
labels so the signal stands out from the noise. Put your print
statement in a condition that’s only true in your error case. And again, always
make a prediction about what your printed message will be before
you read it.
Debuggers are cool and useful, but printing is faster.
It’s tempting to log statements like
try to start out writing coherent messages. Assume someone is going to jump in
and try to help you— are your keyboard-smash logs going to let them help you?
Often while debugging I’ll catch the bug because I wrote a good log
function 'isRedirecting' executed and I saw it on screen at
time when I was certain the function would not be executing.
During long debugging sessions, sometimes you need to abandon debugging
statements that are no longer valuable or slowing you down.
--patch is a way to drop changes from the command line without jumping
through many files.
Learn to read stack traces.
Very often when I solve a bug, I find that the exact issue, or something very suggestive of it, was printing in a stack trace I had from the start.
Systems are complicated, and starting your debugging in or near the right part of the stack can save you hours of wandering.
Dependencies are just other people’s code that’s being used by your codebase. Learn to explore them.
Open-source documentation is great, but even the best projects document only some of the APIs that they’ve exposed. If you’re counting on an open-source library’s documentation to have the answer, you’re working with a fraction of the possible information available.
Get comfortable jumping into your dependency code, finding your bearings, exploring, and narrating what you see.
When you find yourself trying to solve an XY Problem, stop.
XP Problems are questions about your theoretical solution, rather than questions about the actual problem. They sound strange when spoken aloud, like “how do I force React to update a props value, when the prop value hasn’t actually changed?” You’ll know you’re asking one when the person you ask responds with another question.
Implementing the wrong solution isn’t progress.
When you find a line of code that’s important, mark that line so you can return to it.
m<letter> in Normal Mode marks your line. You can return there across
'<letter>. I find this helpful when I’ve been moving through a lot
of files and am losing focus. Return to the mark, jump start my memory, and
git bisect can identify when something stopped working. Learn to
use it when necessary.
I don’t bisect unless I’m really stuck or I feel like the solution is going to be something sneaky and boring. It’s a shortcut around learning how stuff breaks. Sometimes you need a shortcut.
Manual bisects are great too; comment out half of a function and see if the bug persists. If it does, your issue doesn’t depend on the commented code. Comment out half the uncommented code and repeat.
Timebox your solo debugging. Give yourself twenty minutes to an hour to struggle. When that ends, ask for help.
If you can’t get help and it’s an appropriate time to do so, go home. Let your subconscious work on the problem while you sleep.
If you want to cement what you’ve learned, explain the bug to someone else. Learn from it.
If the person is less experienced than you, congratulations; you just taught somebody something. If they’re more experienced, they might critique your explanation by pointing out holes in your reasoning. Now you understand it even more.
A bug in production wasn’t covered by a correct automated test. Solidify the bugfix by writing a test.
Much better than saying “I fixed the bug” is adding “and I wrote a test so it shouldn’t happen again.” Incremental improvements like that are what make a robust codebase.
Here’s the full list of tips:
What makes a real difference in your ability to find and confidently fix bugs?
What are your thoughts on this? Let me know!
Get better at programming by learning with me! Join my 100+ subscribers receiving weekly ideas, creations, and curated resources from across the world of programming.