Debugging is a regular part of my software development work, but as a self taught programmer, I’ve never had anyone teach me a specific step by step process, but I’m not sure a high level debugging process is something that is taught formally, e.g. as part of a Computer Science degree.

I’ve finally found something of a more complete and general guide to debugging, rather than just one or two rules of thumb. It’s David Agan’s ‘Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems‘ (affiliate link).

Although I’ve picked up my own way of debugging (such as only changing one thing at once, or working through the problem methodically), reading this book really helped to crystallize my own method into memorable rules. He uses many practical examples which is really helpful. The book doesn’t give any clickbait-y shortcuts – the first rule (Understand the System) is very clear that you can’t shortcut domain knowledge or work through series of abstract troubleshooting steps without a deep understanding of the system you are working on. This reminds me of being totally out of my depth as a young mechanical engineer, debugging an issue on a DB Schenker Class 66 locomotive with some electrical engineers – and not having a clue what was going on. I instinctively knew some of the rules of how to debug, but without understanding the system I was stuck.

My only criticisms of the book are that some of his rules are written in an idiomatic way so they are a bit tricky to remember what they mean without some explanation, and they are not in a specific order of debugging step by step. David Agan is a hardware developer so most of his examples are from that perspective so a few more software examples would have been more useful for me personally. It’s still well worth a read for any software or hardware developer.

I decided to create my own concise quick reference guide / cheat sheet for debugging anything to refer back to. I’ve summarised each of his key points, and given them more of a software developer perspective with a simple Python example. It doesn’t go into any detail of the specific implementation of the Python debugger so it is still very relevant for any programming language.

 

You can download it here: Debugging Cheat Sheet PDF (with Python Example)

 

I also created the same cheat sheet with blank examples so you can fill your own in for any system or bug your are currently working on:
Debugging Cheat Sheet PDF (with space for your notes)