Slower Debugging

Most debugging starts off too fast.

Someone has encountered buggy behavior in production, or we've noticed something is off about the code we just put up for review. It's moments like these that initiate a debugging effort. These moments tend to have an atmosphere of urgency. Something is wrong and we want to fix it quick, so that we don't let our users down, so that the blame doesn't fall on us, so that we can feel good about the work we've put so much time into. But it is here, at the beginning, that I urge you to slow down.

When the debugging process starts in a frantic hurry, you are bound to miss key pieces of information, you'll follow your unexamined assumptions down a fruitless path, you might cut corners, take half-measures, miss the opportunity to collaborate, and maybe, ultimately, get to a fix that you don't quite fully understand.

This is a painful, disheartening, and time-consuming way to debug.

Instead, slow down and take a couple deep breathes.

Then find a pen and a piece of paper. Start by writing down in complete sentences what the problem is. Be exhaustive. Do this to get the problem out of your head and on to paper. In your head you feel like you understand it better than you do. As you start to write it down, you realize the holes in your understanding and you notice where you've made an assumption that needs to be checked.

Now that you've identified the problem in a more thorough way, you can start to generate theories about why. At this point, you will already be primed to skip over many of the theories that you would have pursued had you jumped headlong into the debugging process. With a better understanding of the problem comes better theories. Write these theories down, on paper. Again, use complete sentences, be exhaustive. Write as if you're describing it to another person on your team.

With these theories in hand, you can systematically work through them. You can start with whichever you'd like. It's good to pick one that feels like the likely culprit or one that would be easy to debunk. With a theory picked out, start writing down the steps you'd need to take to verify or disprove it. Don't just think about the steps, write them down. Then start working through those steps, taking notes about what you discover as you go. If you disprove a theory, note that and move on to the next one.

This process keeps you grounded so that you don't jump to conclusions. The documentation is invaluable if you start to get that lost in the labyrinth feeling -- instead of wondering, "have I been here before?" you can check your notes and see if you're wandering in circles.

This scientific process of debugging will likely lead you to a solution faster than the more frantic approach. When you have that solution, take note of which theory was right and what was required to fix it. Hopefully, you can wrap your head around what went wrong and why. If not, can you identify what the missing pieces are for you. Even if you don't have time to dig into it now, you can always revisit it later to fill in the gaps for your own edification.

For the harder to crack bugs, reach out to a coworker for help (if you haven't done so already). Walk them through your notes. You can have a much more productive conversation with your thoroughly documented process than with your frustrated recollections. As you walk them through each piece, chances are they will see a hole in your investigation. If you were instead giving a summary from memory, it would be harder to point out something that is missing. Continue to document your progress as you work together.

All these written notes become valuable documentation for future debugging. If you encounter a similar issue, you can flip back to your notes and follow the paper trail.

The next time you encounter a tricky bug, remember to slow down, get out a pen and paper, and give yourself a fighting chance.