The Most Important Part of Debugging: Getting a Grip!

Every now and then, I see developers working on bugs for a long time. (In this post, “bugs” mostly means “surprising misbehaviors of features in a web app”, since that's what I'm working on most of the time.) These developers will invest a huge amount of time and effort, but when they explain how it's going, they seem to spin their wheels and are only making very slow, undirected progress. They chip away at the problem from many different angles, hopefully hitting the solution one day.

What strikes me is that these are smart people, working hard on the problem. My feeling is that they could solve the problem in a much shorter time, but their approaching is hindering them.

Recently, I told Timo about this, and while I did, I accidentally created a metaphor: Debugging is like lifting something up and carrying it where it needs to go.

You need to look at the thing, determine it's shape and weight, and find a good way to grip it.

Imagine the humble moving box. Yes, you could take one hand and grip one of the open flaps. But that's so weird. You could take two hands and grip one of the open flaps. Still weird, stop grabbing the flaps. Actually, close the flaps. A typical moving carton has two handles to put your hands into and grip. Additionally, if you rest it against your body a bit, or you get to stretch out your arms, carrying gets much easier.

(Even then, real pros will tell you that, actually, you should carry the box from the bottom, because then you will not rip the handles, and it will be easier to make your arms straight without dangling a box before your legs. But I digress.)

Imagine a couch. If you need to carry it, you probably need to grab quite low, until your hands get some good purchase. Also, you probably want to remove all the cushions first (so important) and get someone to help you.

In a way, the same applies to bugs. You need to find a good spot to hold them. If you notice that you didn't find a good spot yet, don't grip harder. You will just tire yourself out! Put it down for a second, move your hands, grip again.

Don't get me wrong: I know that this is very, very difficult. If it was easy, computers could do it themselves. (I'm not interested in hearing whether LLMs can do this. Don't let them take this from you. It's worth it to be better than an LLM.) It takes a huge amount of skill and experience to know how to grip a problem. But there are a few things that can help you.

Really reproduce the problem. Time and time again, I see people that start debugging without experiencing the bug with their own eyes. Make it easier on yourself: Reproduce the bug, make it easy to reproduce repeatedly (like with an automated test), and only then start changing code.
Eliminate layers. If you aren't sure where exactly a bug happens, remove places where it can hide. Recently, I had to figure out why ElasticSearch in one of our Rails apps sometimes returned wrong results. I tried to skip all Rails code and used curl to send the queries to ElasticSearch directly – and the problem still happened! This immediately excluded 99 % of our Rails app from the debugging journey.
Change the (error) message. Continuously prove that you're on the right trail by changing the output. You don't even have to make the error message better or make it go away. Very often, I put a raise "hell" into the code, just to see that I'm editing the right file, and that the code I'm editing is really getting called.
Notice when you get stuck. Banging your head against the wall feels great and horrible at the same time. Don't forget to take a break, and when you do, ask yourself: Is there something better that I can try?

The next time you're struggling with a bug for a long time, and wondering how you got there, maybe think: How can I get a real grip on this? Good luck.