Zen and the Art of Debugging

Reader, if you are like me, a good part of your development time is spent debugging. It can take hours or days, or more. But, like any skill, debugging is something you can improve upon. Here are a few thoughts on how to improve your approach to debugging. It's something we all do and we can all get better at it.

Note: The following techniques are tool-agnostic. They help whether you use Chrome DevTools, Safari Web Inspector, Firebug, command-line node inspector, Visual Studio Code built-in debugger, whatever

Keep These In Mind

  1. The Program Will do Only What You Ask it to Do
    There is hope, and you will find a solution. In a real development setting, your code may not be the issue, it may be an issue in the library or service dependency.
  2. There are Almost no Intermittent Issues
    "Intermittent" issues can almost always be reproduced consistently using clearly written steps that are carried out precisely. They look intermittent only because the steps are not clear or complete enough, or the steps are not being followed precisely each time the test is run.
  3. Find the Cause before you Find the Fix
    We often start "fixing" an issue before we have even identified a cause, let alone the root cause. Without knowing the cause, a "fix" is not a fix. It's a patch. And it will likely cause more issues than it fixes.
  4. Make Small Changes, then Test
    If you make a lot of changes before you test - you are making it more difficult to isolate the one change, or small set of changes that made the difference.
  5. Keep a record of what you have tried
    To find a issue sometimes you have to know what is not an issue. Make a list so you know what you have changed and how then you can exclude those as possible contributors.

A Test Plan Can be Key

Creating a detailed test plan may take 30 minutes, but debugging can take hours or days a test plan is worth the time. It will force you to think about the problem before jumping in.

Once your test plan is set, follow each step exactly. A seemingly trivial inconsistency in a step during user interface debugging can make a behavior look intermittent.


Give Yourself a Break

After that hour, or afternoon stop and take a break. If that doesn't help, call it a day. Go to bed. Don't think about it. You will have a different perspective, more ideas, and perhaps a solution the next day.

Recognize When you Need Assistance

If after that time your still frustrated, walk over to a teammate and debug together.


You Fixed It! Probably?

Don't check in yet. First, confirm that it is really fixed and not a fluke. Run through your entire test plan a few times.


Debugging Tips

Debugging may take a while. It may involve many of rebuilds, file saves, server restarts, browser refreshes, etc. It's tedious. Any time shaved from these actions will shorten iteration time and make it just a little more bearable. Some common time-savers that are easy to overlook follow: