Debug By Describing

When trying to find a non-trivial bug, write down a description of the bug as if you're trying to help somebody else find it. Do this in a text file, and paste in test cases that do or don't demonstrate it, backtraces, hypotheses proved disproved and unknown, and other information.

This is perhaps a variation on ProgrammersNotebook. Keeping a notebook can interfere with the MentalStateCalledFlow, so I'm not sure it's a good idea to do it all the time.

Many people have observed that just by starting to explain a bug to some other person they put their thoughts in order and find the bug with no need for any suggestions. Some people say this works well enough if the audience of the explanation is a co-worker or family member who doesn't even understand the problem but who is a patient listener. If there's no human available, then keeping a written description can be a good substitute.

Perhaps PairProgramming allows continuous description as the two people work through the bug. Documenting untried but interesting hypothesis is like having FixmeComments in code.

If all else fails, once you've written a cogent description of the bug you can send it to somebody else for their ideas. Having things written down also nicely supports the SleepOnIt? solution: when you have a new idea in the morning, you can check whether you've already tried it or not.

-- MartinPool

I'm one of those people who often finds bugs just by describing the code to a co-worker, and it's true that the co-worker's understanding is not crucial to the process. I've never tried it with a non-programmer, but I've long surmised that that would work just as well. It never occurred to me to try writing a description, but I imagine that would work pretty well to. I think the major thing is that when you launch in to an explanation to another person, you feel obligated to describe assumptions that you take for granted when trying to just think through the problem. Another advantage might simply be that you shift your brain out of problem solving mode into a completely different mode: Your conscious effort is focused on explaining what you know, not figuring things out, and maybe this allows your sub-conscious to take a whack at solving the problem.

-- CurtisBartley

The book PracticeOfProgramming? by Kernighan/Pike claims that a university forced students to explain their problem to a Teddybear before bothering support staff/instructors. :-) Like you said, the listener's understanding doesn't always seem to be relevant. -- GunnarAnderson?

Modern idea: Tell it to the Furby. It's at least as smart as any of us. ;-> -- JeffGrigg

: The responses are probably better, too... (-:

If Furbies are beneath your dignity, try a CardboardAnalyst.

I work alone, but I talk to myself a lot. It has a similar effect. It may be better, because I talk quicker than I write and I do have techie knowledge and can detect when I'm trying to fudge an issue perhaps better than other people could. -- DaveHarris

So, Dave ... which one of you wrote this?

The other one. -- DaveHarris

I've heard Ward describe this activity/state as ReflectiveArticulation, a beautiful phrase.

--JamesCollins

This technique seems to work especially well when I'm writing up a bug report or preparing to send a note to a support forum or mailing list. As I further describe the problem in the best way to approach the list/forum members, I often suddenly find that I also understand the answer.

-- Vicki Brown

CategoryDebugging