Philosophy of Debugging

This is not intended as a guide to debugging, but as psychological and philosophical observations of the process. These are some of my guiding principles to debugging.

Do not be ashamed; show the wee critters to your friends

Ask a friend, adviser or co-developer to help you debug your code. Bring them over and start explaining the problem and the code on screen. A very common experience is that two seconds later you realise what the problem is; despite previously wondering about it for hours. They, on the other hand, may still be baffled - not quite understand what's going on - but despite this, you fixed the problem.

So, do not be ashamed of bugs in your code - it happens to everyone, and talking about it helps, even if the person you talk does not really understand the problem. Trying to explain the problem is a good way to make progress on solving it.

Be Patient, be open minded

Bugs can take a long time to find, getting inpatient usually stops you thinking and makes you tense. You need to be relaxed to think and you need to think to debug. Bugs often happen because you did not think widely enough about the problem. Thus you need to expand your understanding of the code and the problem. You need to be open minded: what assumptions does your code make, and what happens if you don't respect them?

Be Scientific: make the bug into a (preferably simple and small) repeatable phenomena

Treat the bug like some strange physical phenomena, or animal: you are trying to understand it. To debug, it helps a lot to have a repeatable example. The first step is not to randomly permute you code! First try to lure the bug into showing itself. Once you have a repeatable example, which is a good thing, try to make the example as convenient for you to understand as possible. Spend time getting a nice small example. The syntax and even the names of variables do matter. Rename everything to the most sensible names. The first step is to make things as simple as possible - even if you think it makes the bug "worse", or your example "more wrong"; it is worth doing.

Solve the first bug first

If you notice a minor oddity that you do not understand, but which is not problematic enough for you to consider it a bug, then go back and understand it first. Chasing a bug when there are strange things going on is very hard. Often the "bug" is just another manifestation of an earlier oddity. Be disciplined: make sure everything makes sense and as soon as it starts to become odd, investigate it, and understand it. Many bugs are misunderstandings.

Psychology and Monsters

Debugging can be difficult psychologically, it is depressing when it goes wrong and you do not know why. My first maneuver in addressing this is to give the bug some respect, call it a monster, and give yourself a heroic status as a hunter of code-monsters. This makes it more fun. The analogy is good also - monsters lurk in the dark depths of complicated labyrinths. In fact, the analogy gives some hints at how to hunt bugs.

Lure the monster into familiar territory

Following a nasty monster into a complex labyrinth of code is very dangerous. If you are not familiar with the surroundings, you will have a very hard time catching the monster. If you have left your code in a mess, and cannot understand it, and the monster is not obvious, then you should rewrite the code cleanly. Chasing monsters in the dark is dangerous! It will lead you to getting frustrated and depressed; even worse: the monster may kill your enthusiasm, and you will then be unable catch it.