This is a guest post from the friends of the Flaky Build. If you would want do a guest post about something important to you (and software engineering related) get in touch by emailing me. Thanks again Juhis ❤️.
Hello there! I’m Juhis and Onni invited me to write a guest post on his blog to share my experiences in the software industry. I chose to write about debugging and wanted to provide you, dear reader, five practical tips that can help you become better at figuring out what’s wrong when the computer says no.
Detective mindset
An effective debugger is someone who approaches the problem at hand like a detective. A great detective leaves assumptions at door and avoids making guesses. Instead, they follow clues and breadcrumbs, examine evidence and come to conclusion based on logical thinking.
I’ve often seen developers - both juniors and seniors alike - approach problems by staring at the code and hoping the issue shows up. Or they jump into conclusions as they imagine they know where the problem is. And then they spend minutes, even hours on a wild goose chase only to find out, they were in the wrong place.
Tip 1: Follow an iterative step-by-step process as if you knew nothing about the codebase at hand.
- Make sure the code you are looking at, is being run. A print statement at the start of each function that you look into is a good quick way to confirm that.
- Replicate the bug. Make sure you know how to trigger the bug, otherwise it will be hard to know if you’ve solved it.
- Examine the state: print out the state of variables or jump into a debugger to see what’s happening each step of the way.
I find that repeating these three steps as I move mentally around the codebase is enough to find the source of pretty much any bug.
Invest in learning your tools
Software development is an industry where we have an abundance of tools available to us for any given task. Most of them are even free or open source so the financial investment is low. You do still need to invest your time into learning and mastering them.
In my opinion, debugging is a two-part skill: the mindset and processes I talked about in the previous section need to be combined with great tooling to become effective in finding and solving the problems.
In our day-to-day work, it’s easy to find a set of tools and never really look outside the box to see what else is out there, what updates your tools have recently gotten or what other people are using to solve their problems.
Tip 2: Get comfortable with printing, logging, debuggers and code editors for your language. It lets you focus on the problem at hand instead of spending your energy on figuring out how to use the tools.
For example in Python world alone, there are dozens of different debuggers to choose from. There’s the built-in Python Debugger, a terminal UI debugger PuDB, a web ui debugger web-pdb and birdseye - only to name a few. Different people are at their best with different tools so explore, try them out, pick what feels the best and learn the ins and outs of it. And keep an eye on updates and changelogs to see what new features are being added.
Printing is the best debugging tool
As I’ve been writing and speaking about debugging in various places, one thing that has surprised me is the attitude towards printing as a debugging method.
I’ve had people share with me that their teammates have told them printing is bad and a lot of people have come to chat with me after a talk, telling me how relieved they feel that someone told them their printing approach is not a wrong approach.
Printing is the best debugging tool because it has the lowest friction. You don’t need to install or configure anything, it takes a couple of seconds to write a print statement, it’s relatively easy to find the outcome from the printout and if the problem ended up being simple, it’s by far the fastest way.
Tip 3: Don’t hesitate to use print liberally!
This means you’re more likely to actually use it, instead of choosing a less effective path of staring at the code and pondering. Printing isn’t the most powerful or most complex tool and there are often moments where it’s not enough – that’s the moment when it’s time to move to more powerful tools like debuggers – but it’s a great starting point for every debugging expedition.
Share and learn with your colleagues
Jenn Creighton said it well in her talk Now And Then: Debugging Async JS said it well:
“The best debugging tool is knowing something well.”
She talks about how working with a technology, an approach and a codebase accumulates experience where you see an issue and it reminds you of something you’ve experienced before, giving you a bit of head start in choosing which assumptions you validate first.
Often this accumulated knowledge is personal. But it doesn’t have to stay that way. Just like I encourage you to share your tips with the tooling, I encourage you to share your experience with bugs and debugging in your project or codebase with your team.
Tip 4: Write down your debugging expeditions and every now and then, organize a lunch and learn or Friday afternoon learning session where you go through what kind of bugs you’ve encountered and how you solved them.
Those stories don’t have to be about any huge bugs and heroism but rather everyday experiences of regular things. If I learn five debugging stories from colleagues that relate to how code with timezones can cause issues, I’m way more prepared to tackle a bug related to timezones when I run into one.
Talk to the ducks
If everything else fails and you’re still stuck, it’s time to bring out the ducks. Rubber duck debugging is half inside joke in the industry and half actually useful and effective way to find clarity in your problems.
In a nutshell, here’s how it works:
- Pick up a rubber duck (if no ducks are around, other animals or in a pinch, a colleague works too)
- Tell it what your problem is
- Tell it what you’ve tried so far and how they have not worked
- Ask for guidance
In my experience, before the duck manages to answer, you’ve figured the solution yourself.
Tip 5: Talk to ducks or write down your thoughts to gain clarity and spot gaps in your assumptions.
The reason it works so well is that normally when we think about our problems in our head, our brain is really good at lying to us. Since it’s your brain talking to itself, it skips details. You think you’ve tried something when you actually forgot or skipped it because it seemed obvious. By talking through what you’ve tried and what the problem is, you force yourself to talk through all the details because we tend to notice the missing steps when we talk them through.
Noticing the missing steps helps us often figure out where the problem lies and we arrive at either a solution or at least get one step further in the process.
When I lived in Berlin, under a tree in our neighbourhood lived a council of ducks. So when my own duck trio wasn’t enough, I could take a walk and go ask help from the council.
I hope these come in handy for you. Happy debugging 🦆!