The debugging flowchart

A few weeks ago my team and I faced a really frustrating bug. We worked on it for almost five days, and a logical explanation remained to be seen. They started debugging and couldn’t find any insight that led to a fix for three days.

I joined them and spent two more days following their steps. I validated their approach to understand and reproduce the bug in my local. Then it struck me and I checked one thing we didn’t see before: dependency versions. Turned out that we were behind the version where the working code was. In awe, the team asked me how I came up with checking versions. I told them that I have been in these situations way more times than they have been. It was my own experience that drove me to that insight, which ultimately led to the fix.

Truth is, I indeed have been a lot of times in debugging rabbit holes that seem endless, which eventually turn out to be easy fixes. But I should’ve checked the dependency versions way before the five days it took us to get there. It took us so long because we were not disciplined: it would’ve been way easier if we have had some sort of checklist to guide us along the way. Have you been in those long-lasting debugging marathons I’m describing? Have you felt the pain of spending hours looking over and over the same code again? Have you felt dumb every time that, after sleepless nights, you find out that the fix was a couple of lines away?

I have been there too, and I wondered how would it be to have a guideline to remind myself what to do next. I took a stab at defining that sort of algorithm, in what I called the debugging flowchart. This is a condensed, general-purpose step-by-step guide to what to check when facing a bug. I made it comprehensive enough to catch as many scenarios as I’ve seen. Yet, the intention is not to be the ultimate debugging experience. There might be rough edges that you, my thoughtful reader, have banged your head against and can point me out. I created this flowchart in the awesome Excalidraw, and since it creates JSON files, I figured it could be easily versionable. So, if you feel there’s a missing case or a helpful step I didn’t consider, please feel free to submit a PR with your updates. I’d love to discuss your ideas on GitHub so we can enhance this guide and help us be better at debugging.

And now, without further ado, the flowchart.

Thanks for reading! I hope this flowchart helps you in the same way I think it’ll help me. As always, open to comments and questions. See you at your next debugging session!

Looking to partner with an experienced and excited group of digital product and design developers? Ask them your questions and see what Zemoga can do for you.

About the author

Andrés Zorro is a Principal Architect with a Front-End background. He has over twelve years of experience developing and executing end to end solutions, and has helped guide teams by sharing his findings across multiple countries and timezones during this time.