A Beginner’s Guide to Debugging for Beginners
Basic Strategies and Principles for a Less Stressful Debugging Experience
“If debugging is the process of removing software bugs, programming must be the process of putting them in.” — Edsger Dijkstra
Bugs. They’re inevitable. In the same way that most writing is revision, most programming demands debugging. That means developers get lots of opportunities to confront our own understanding. It’s great. Okay, it doesn’t always feel great. If I can appropriate another writing truism from Dorothy Parker, I hate debugging — I love having debugged. And while I have occasionally tried arguing or even bargaining with my laptop, I’ve never found it a particularly effective method. Luckily, we have lots of tools and strategies that are much more effective. Below, I’ll outline a few that I’ve found particularly useful for arriving at the coveted state of having debugged.
But first… do you have a moment to talk about unit testing?
Write a Test
In an ideal world, crimes against maintainability and the user experience are caught before they are committed. That means saving time debugging might mean spending time writing tests. Tests allow us to make assertions about the shape of our data and expected output for our functions and components before a mistaken assumption becomes a problem. It’s a much more elegant solution than printing or console.logging until the problem reveals itself. Of course, that requires investing time in learning testing. If you’re not there yet, have no fear, we have options.
Read the Error Message
Now, say we haven’t written tests or we’re just humans whose codebase hasn’t reached 100% coverage. If we’re encountering our bug in the wild, we’re likely to be confronted by a helpful message showing us the error of our ways… more or less. Error messages can present as cryptic one-liners, the computer equivalent of a shoulder shrug, or daunting walls of text with lots of cascading failures. However, at a minimum, try looking at the very top. The first problem the computer encountered is likely to be the source of the problem. Even if it doesn’t quite get you there on its own, it will probably provide you with a file and line number; that’s a great place to start.
As beginners, the chances our problem has never been encountered before are pretty low. It’s worth leaning on the wisdom of those who came before. Plugging the error into Google will likely return a slew of blogs, GitHub issues, and Stack Overflow posts on similar problems. A little research could go a long way to point you in the right direction.
Check for Typos
Mismatched quotes or brackets, a period where a comma belongs, a comma where a period belongs, variable or function misspellings, there are so many ways to be off by one character. I’ve found it’s a good idea to try ruling out simple grammatical errors before spending hours questioning your sanity and grasp on basic logic just to find a missing semicolon. It might also be a good idea to check the docs and make sure your syntax is correct.
Make Your Own Assertions About Input and Output
Just because we haven’t formalized our assertions as tests, doesn’t mean we can’t start doing some legwork ourselves. I find it helpful to articulate how I’m expecting my inputs and outputs to look. Then, if I’m lucky, I’m just a print/console.log away from confirming or refuting those assumptions.
Inspect Your Input
Often enough, errors can be the result of bad assumptions about the shape of our data. This is especially true if we’re pulling that data from an external API or passing it down through callbacks or React props. In the case of external APIs, it might be worth using a tool like Postman to familiarize ourselves with the way data is structured when it arrives. If our input is in-house, we can always fall back on print/console.log inside our function. Or, we can move forward with a tool custom-built for the job…
Debug with the Debugger
Check Your Logic
If we’ve made it this far, our input looks fine, and our variables add up, it’s time to consider the possibility that we really are mistaken. At that point, there are a few options that boil down to more articulation of expectations. Sometimes all we need to see a problem with our logic is to hear ourselves explain it. We can start by rubber ducking — just talk through your thought process with any old inanimate object. I personally use stress bear:
If that isn’t helping it might be time to get another human involved. Bring in a friend or colleague and start from the top. If you’ve tried to no avail, or you don’t have any colleagues on hand, it might be time to make your first Stack Overflow post!
I hope that helped! Feel free to leave a comment if you have any other tips. Good luck and happy bug hunting!