✋ My 5-step process to debug any issue (I am faster than anyone else)

This post introduces a systematic method to tackle software bugs by leveraging proven techniques, just like a researcher would. This is how to become more effective and efficient software engineer

Debugging something broken is hard, boring, and tedious.

Many people would approach this like kids approach math problems. You hold your head with your hand. You write numbers on the paper without understanding why…

I suggest something better: Approach debugging like a scientist working in a lab.

#1 - A scientist would read the work of other researchers, rather than reinvent the wheel

When debugging a problem, don’t assume you are the first human on earth facing this kind of issue.

If you have a problem at hand, check forums like stack overflow. Check your company’s Slack channels. Also, check in search engines and LLMs.

And when you don’t have a problem at hand, keep up to date reading about the problems other companies are facing. The problems other teams in your company are facing…

Books are one of the best ways to learn patterns of what many companies face. In the system design space, I recommend the books of Alex Hu: Volume 1, Volume 2, ML system design book

#2 - A scientist would formulate questions, both from their work and others' work.

Insanity is doing the same thing over and over again and expecting different results - Albert Einstein.

Why would you keep building your project, hoping for something to go different this time?

Instead, formulate questions from the error logs and draft different hypotheses of what could be happening.

#3 - A scientist would work systematically on proving or rejecting these hypotheses.

Once you have a question, you want an answer to it.

And like a scientist wouldn’t do experiments on humans directly, you may not be able to experiment on production.

Find your testing ground, such as a lower environment, A/B testing in prod or doing a Proof of Concept.

You don’t make many assumptions, but work based on data you have collected

#4 - A scientist wouldn’t stay silent for months in their lab. They would soundproof their work with peers

Once you are very focused on something, you are tunnel-visioning on it and you are missing what’s around.

There are 2 ways I know to broaden your focus again: 1) Talking to people, and 2) Taking a break, going for a walk, and allowing your mind to wander

I was debugging a problem a couple of weeks ago. The service didn’t deploy to AWS ECS, but I had no idea why. The logs just stopped at some point without any error. I compared the logs of a successful deployment and I couldn’t find why the next line wouldn’t appear.

After talking with a peer, he told me it would be weird if an internal technology allowed the naming we tried to use for lower environments. In the industry, there are many names for them (alpha, beta, gamma, pre-prod, release, staging, prod…), but Amazon only used a few.

When checking for the log messages that flowed the last, I found a list of the supported names. And using a supported name got the service to deploy.

I had already tried things. I tried a deployment a second time to discard transient issues. I compared successful and failed deploys to find what was coming next. But talking to someone gave me a new hypothesis to prove that I didn’t come up with by myself.

#5 - Once you find something, you share it widely for people to benefit from the new knowledge

When you solve a bug that other people can face, make sure to share your steps to overcome it and the learnings you took.

It’s inefficient for an organization to have different people solving the same problem. Leave traces of your debugging for others to find later.

🎯 Conclusion

There’s a reason software engineering is called engineering.

You can’t build great software brute forcing your way

Working systematically will give you better results than anything else.

Don’t act like a kid solving a math problem. Act like a professional!

🗞️ Other articles people like

😎 My strategy to become a TOP 1% engineer

My strategy to deliver more results

How to plan your growth

Ask First, Code Later: The single, most important question

👏 Weekly applause

Here go some good reads for this week:

1. 12 Essential Debugging Tools for Software Engineers by

   High Growth Engineer
   → After knowing my process to debug, if you are looking for specific tools, take a look at Jordan’s article.

2. How to Scale an App to 100 Million Users on GCP 🚀 by

   System Design Newsletter
   → This one will give you the patterns I talked about for things like system design interviews. You don’t start high-scalability from the start, but you’ll need to adapt as the user base grows

3. The secret of the best engineering manager I know by

   Anton Zaides
   → A good one in relationships at work. When I told you the story of the environment that didn’t deploy, I solved it thanks to having a good relationship with someone to talk to.