Debugging: A Structured Approach

Debugging is an inevitable part of software development. At its best, it’s a fun puzzle and a chance to learn. But it’s also easy to get lost.

It is about chasing the right lead – and it’s just as easy to go in the wrong direction and spiral into into a frustrating, time-consuming, and even burnout-inducing experience.

Common pitfalls include overlooking simple explanations, making false assumptions, or focusing on the wrong part of the system.

Here are some language-agnostic tips.

Not everything applies to every problem, so use the ones that are relevant.

Try Again

Before diving deep, simply try again.

• Make sure it's not a one-off issue.
• Pay closer attention to what’s happening.
• If the issue is complex, note down the steps to reproduce it.
• If multiple errors occur, always start debugging from the first one.

Be at the Right Place

Ensure you’re working in the correct environment.

• Are you editing the right code?
• Are you looking at the correct app (e.g., production vs. staging vs. local)?
• Is the app connected to the correct database?
• Could caching be affecting the content?
  • Cache could be from network layers, build tools, or external providers.
  • Validate this by adding console.log statements, breakpoints, or modifying content/CSS.
  • Make a scene – try intentionally crashing the entire app.

What Changed?

Narrow down the problem by knowing what changed.

Consider how the problem came into existence:

• Was the feature not implemented to begin with?
• Or, more likely, was there an erroneous change made?
• Did you install new packages or pull new commits?
• Can you roll back and compare differences? Use git bisect.

Assume Nothing

Narrow down the problem by testing your assumptions.

It might not be your fault – third-party libraries or incorrect documentation could be the issue.

• Are you referring to the correct documentation version?
• If you suspect a library issue, do a quick GitHub issue search. It takes just a minute.
• Have you tried restarting the app or your computer? – Yes, it can really resolve odd issues sometimes.

Reproduce Fast

Narrow down the problem and create a minimal reproducible example.

A minimal test case is necessary to:

• Confirm when the problem is fixed.
• Optimize validation to make debugging more efficient.

Consider:

• Removing authentication, disabling validation, or hardcoding field values.
• Writing a script that automates test execution (try Chrome's Recorder).
• Ensuring the test case requires minimal manual interaction.

In some cases, you can brute-force by enumerating all possible solutions (for example, order of arguments, combination of flags):

• Try each potential fix and execute your test script.
• This might eliminate the need to dig into documentation.
• Work backward once you know the final answer.

Bonus points if you convert it into a permanent test case.

Try Later

Stuck? Take a break.

• Explain the problem to a rubber duck (aka a colleague).
• Walk away, eat food, get coffee, and return with fresh eyes.

Happy debugging!