5 Generic Debugging Tips

These are some practical tips to help maximise your chances of success when debugging software problems – especially those hard to isolate problems. Most of these tips will seem like common sense but I am constantly amazed at how often they are overlooked! I’ve deliberately tried to keep these at a generic level and not tie them to a specific language so that they may be of relevance to most people.

  1. Think: If you can quickly build and test your application there is often the temptation to keep trying things until the bug goes away. It is easy to get caught up in a cycle of “make a change – build – test (fail) – make another change …” without really stopping to catch your breath. The danger with this approach is that when the bug goes away it is sometimes difficult to tell if the bug is fixed or if you have just solved a symptom. Although frustrating, it is sometimes a learning experience to have to debug an application or system that takes a long time to rebuild and test. This forces you to take a step back and to think carefully about what you can glean from your current data and what the next step should be. This will help you to better understand the nature of the problem and in doing so it will help to find the root cause more quickly.
  2. Baby Steps: This is a really obvious but often overlooked practice. When debugging always take baby steps and only change one thing between tests. It is often very tempting to make a couple of changes or to skip a step, but this invariably results in an inconclusive test result and you will end up backtracking to figure out which change caused a change in behavior.
  3. Simplify: Try and reproduce a suspect piece of code in a stand-alone environment. For example if a particular algorithm is miss-behaving, try and replicate this behavior in a simple application that only contains the algorithm and may be easier to control and debug. Similarly, if debugging issues in a kernel, it is often possible to replicate the code at a user level which is a much more friendly debug environment.
  4. Tools: Become intimately familiar with your tool chain. Take time to learn the power and quirks of your unit test environment, debugger, memory leak checker, compiler, etc. If you develop on multiple platforms and use different tool chains on those platforms then learn them all!
  5. Challenge Assumptions: Assumptions can be dangerous. How many times have you assumed that a particular piece of code is working only to find you many hours later that it contained the bug that was the root cause of the issue you were debugging or that it behaved subtly different than what you expected? In general it is good practice to assume nothing and to challenge all assumptions that you find yourself making.