Debugging 101 - Drat! Now What?!

What to do when something goes wrong.

(A presentation and interactive debugging session for the February 18, 2009 MacChamp (Apple User Group) meeting - though virtually all of it is applicable to any debugging scenario.)

Intro: The steps below may seem daunting, however this is the typical process - even if you call someone else for help, it can be handy to know. For instance, it removes some of the mystery and can help you gather critical info you might otherwise have missed. And every advantage to get you closer to a solution and more quickly on your way, is a good thing.

Step 1: STOP!

• Don't make things worse.
  
• Take a moment to assess; is it a genuine emergency?
  
• If immediate action is required, do what's absolutely necessary and then re-assess. (Ex: Dropped mobile phone in puddle: IMMEDIATELY remove battery!)

Step 2: What happened?

• Before you can fix it, you must understand just what occurred.
  
• Understanding requires hard (precise) information.
  
• Write down the time it is NOW.
  
• Write down when it happened:
  
  • If known: The exact time, using the clock on the problem device if possible.
    
  • If not known: When was the last time things were OK? How certain are you of that?
  
  
• Take snapshots:
  
  • Of the screen:
    
    • Shift-Control-3.
      
    • Use a camera if need be!
    
    
  • Of specific files:
    
    • Copy to ANOTHER disk.
      
    • If there are possible problems with a disk, avoid making any changes and especially adding any files to it. Just about anything can cause changes...
    
    
  • Of a whole disk:
    
    • CCC, SuperDuper, Disk Utility...
  
  
• In as much detail as possible, write down:
  
  • What you were expecting.
    
  • What actually happened.
    (Nothing is too small to mention; it's like "brainstorming".)

Step 3: Backups?

• What's the state of your backups?

Step 4: Background.

• List ANYTHING that happened recently that was out of the ordinary.
  
• List EVERYTHING you changed recently, REGARDLESS if it seems unrelated.

Step 5: Why?

• Why did it happen; what's the cause? Using the info you've gathered, generate some theories.
  (ex: Juxtapose what happened with what you were expecting.)

Step 6: Form a plan.

• For each theory, develop a test plan.
  
• Flesh each plan out in as much detail as possible, into a step-by-step checklist.
  (This is important; it may indicate the solution or help avoid a problem.)
  
• TIP: Test one thing - the smallest thing possible - at a time.

Step 7: Backups?

• Should you make additional backups, if possible, before doing anything?

Step 8: Test theories methodically.

• Use checklists & write down results at each step; it may be necessary to backtrack.
  
• Don't make things worse; change as little as possible.
  
• If a theory looks promising, retest to confirm *before* making changes.
  
• If no theories remain, review the info you now have; this may lead to new theories.

Step 9: Fix?

• If you think you have a fix, try it (one at a time!) and take notes about what happens.
  
• Retest to confirm.
  (Better to find out now, that it's not really a fix.)
  
• If a promising fix doesn't pan out, review the info you now have; this may lead to new theories.
  
• If a fix works, does it indicate anything that can be done to avoid problems in the future?

Step 10: Clean up.

• File your notes away; you may need them later; ex: long-term effects, multiple variables.