Your Five Step Debugging Guide: Part 1

Last week I gave you some general tips and tricks. This week, I'm giving you a specific, 5-step script to follow when debugging your code. Without further ado:

Your 5-Step Guide to Debugging

1. Ensure you can clearly articulate the symptoms of the defect and reliably reproduce it. (You are here)
2. Define the boundaries in your code within which the defect could exist.
3. Form a hypotheses about the cause
4. Test hypothesis
5. Begin again at Step 1 until you can demonstrate unambiguously that the defect has been resolved

I'll spend one day on each step this week, giving you a little more detail and color. So for today:

1. Ensure you can clearly articulate the symptoms of the problem and reliably reproduce it

Articulating and reproducing the problem are two different things, but they are so interconnected that I combined them into one step. If you can't describe it and you can't reproduce it, then you won't know when it's fixed.

Begin by describing, out loud, the symptoms of the problem. Be as specific as you can, because assumptions are the enemy of effective debugging. What were you doing when it occurred? How did the defect manifest itself? If there was an error message, what was it? You want to create as complete and unambiguous of a picture of the defect as possible, because as you work through this process you'll likely move through some interim states where your code still isn't behaving as desired, but it's behaving differently than originally observed. For instance, if you've only stated that the process errors out, you may not notice if it begins erroring out with a different message.

Can you reproduce it reliably? I can't stress this enough. If you can't reproduce it reliably, you won't know when you've fixed it. And, in the process of making sure you can reproduce it reliably, you'll probably refine your description of the defect from the paragraph above. Reproduce the issue 5 to 10 times in a row before you move on to step 2.

And remember, you're refraining from forming any theories about the cause. At this stage, you are just fact-finding.

Tomorrow... more fact-finding.

Read Step 2

Next Up:
Your Five Step Debugging Guide: Part 2

Previously:
Keep a Bug Journal. Really.