Rules of Debugging

September 21, 2022    debugging tech

Here is a list of David J.Agan’s timeless and universal rules of debugging. As the author notes in the book - Memorize them. Tape them to your wall. Tape them to all of your walls.

  1. Understand the System: Read the manual. Read everything in Depth. Know the Fundamentals. Know the road map. Understand your tools. Look up the details
  2. Make it Fail: Do it Again. Start at the Beginning. Stimulate the Failure. Don’t Simulate the Failure. Find the uncontrolled condition that makes it intermittent. Record everything and find the signature of intermittent bugs. Don’t trust Statistics too much. Know that “that” can happen. Never throw away a Debugging tool.
  3. Quit Thinking and Look: Get Data First. Don’t just do Complicated repairs based on guess game. See the Failure. See the Details. Build Instrumentation in. Add Instrumentation on. Don’t be afraid to Dive-in. Watch out for Heisenberg. Guess only to focus the Search.
  4. Divide and Conquer: Narrow the Search with successive Approximation. Get the Range. Determine which side of the Bug you are on. Use Easy-to-use test patterns. Start with the Bad. Fix the bugs you know about. Fix the noise first.
  5. Change One Thing at a Time: Isolate the key factor. Grab the brass bar with both hands (i.e., understand what’s wrong before fixing). Change one test at a time. Compare it with a good one. Determine what you changed since the last time it worked.
  6. Keep an Audit Trail: Write down what you did in what order and what happened as a result. Understand that any detail could be the important one. Correlate Events. Understand that audit trails for design are also good for testing. Write it Down!
  7. Check the Plug: Question your assumptions. Start at the Beginning. Test the Tool.
  8. Get a Fresh View: Ask for Fresh Insights (aka explaining the problem to a mannequin/dummy). Tap expertise. Listen to the voice of Experience. Know that help is all around you. Don’t be Proud. Report symptoms (not theories). Realize that you don’t have to be Sure.
  9. If you don’t Fix it, it Ain’t Fixed: Check that it’s actually/really fixed. Check that it’s really your fix that fixed it. Know that it never just goes away by itself. Fix the Cause. And, fix the Process.