The Five Stages of Debugging Someone Else’s Code

Every developer has been there. You open a file you didn’t write, scroll through it, and feel something shift inside you. It’s not quite grief, but it follows the same trajectory.

Here’s the journey we all take when debugging code written by someone else—or by past versions of ourselves.

Stage 1: Denial

You stare at the function. You read it again. There must be something you’re missing, because surely no one would have written it this way on purpose.

def processData(d, x, flag=True, flag2=False, temp=None):
    # TODO: refactor this
    if flag and not flag2:
        return d[x] if temp is None else temp
    elif flag2:
        return None  # ???
    return d

“This can’t be right,” you mutter. “Let me read it again.”

You read it three more times. It doesn’t get better.

Stage 2: Anger

The denial fades and something else takes its place. You notice the function is called doStuff2_final_FINAL. There’s a comment that just says // fix later. The “later” was four years ago.

Questions flood your mind:

• Who approved this pull request?
• Why are there six nested if statements?
• What does temp actually hold? It’s used once and never explained.
• Is that variable named data2 because there’s a data1? (There isn’t.)

You consider adding a strongly-worded comment. You don’t, because you’re a professional. Barely.

Stage 3: Bargaining

The anger subsides into something more pragmatic. Maybe you don’t need to understand this code. Maybe you can work around it.

“What if I just wrap the whole thing in a try-catch?”

try:
    result = processData(d, x, True, False, None)
except:
    result = None  # good enough

You know this is wrong. You do it anyway, telling yourself you’ll come back to it. (You won’t.)

Stage 4: Depression

The workaround didn’t work. Now you have to actually understand what this code does. You open Slack.

“Hey, do you have a minute to explain what processData is supposed to do?”

The person who wrote it left the company two years ago. The person who might know is on vacation. The documentation is a README that says “See code for details.”

You make coffee. It doesn’t help, but it’s something to do with your hands.

Stage 5: Acceptance

You’ve tried everything else. It’s time for the nuclear option.

git blame processData.py

The output loads. You scan for the offending lines. You find the commit hash. You look at the author.

It was you. Three years ago.

The commit message says “quick fix, will clean up later.”

The Real Lesson

We’ve all written code that future developers (including ourselves) will curse. The difference between junior and senior developers isn’t that seniors write perfect code—it’s that seniors know they’re writing code someone will debug later.

Some practical takeaways:

• Name things like you’ll forget context – Because you will
• Comments should explain why, not what – The code shows what; comments should explain the reasoning
• “Temporary” fixes need expiration dates – Add a TODO with a date or ticket number
• Write code for the confused developer at 3 AM – That developer might be you

Every codebase has archaeology layers. The best thing you can do is leave your layer a little cleaner than you found it.

And maybe, just maybe, delete doStuff2_final_FINAL while you’re at it.