The handover. This is something that every single software developer will have either given or received at some point (sorry bedroom coders).

It’s a necessary evil. The problem, let’s be honest, is usually an absolute disaster and a poor hit show.

What’s going on, and what can we do to make this better?

The Ideal

A handover should involve documentation. It should be neatly organized, with a clear set of explanation. What looks like a confusing mass of paperwork should become clear as a series of walkthroughs revealing a smooth transition for a developer to move from newbie to a confident and supported productive developer.

Behind the documentation there are people. They help, guide and mentor. They use the documentation but also are intensely human and bring that humanity into the process.

Overall, this has never happened to me.

The Reality

This is what really happens, at least in my experience.

Someone metaphorically throws a flaming laptop at a new developer, laughs, and shouts “good luck, sucker”. They quietly get up and leave.

If you’re on the receiving end of this, you generally need to beg your colleagues to give you permission to be able to access the repo. At the same time, your manager will measure your “time to first commit”.

It’s rubbish all around.

The Stages of a Developer Handover

When you join a new team, your emotions will run high. You’ll need to deal with the following stages of the developer handover.

Recognize any of there?

False Hope

“This is my code”

Ah, the calm before the storm. The outgoing developer introduces their code as if it’s a well-oiled machine — logical, structured, and easy to follow. They might even smile, lulling you into a false sense of security. You foolishly think, Maybe this won’t be so bad.

You are wrong.

Abandon All Hope

“It’s your problem now.”

Reality sets in fast. You start asking reasonable questions:

• Where’s the documentation?

• Why is there a 2,000-line function named finalVersion2_REAL_final.swift?

• What exactly does fix_this_later_but_it_works.js do?

• Why are there three different date formats being parsed inside a single function?

The outgoing dev shrugs. “You’ll figure it out.”

No Takebacks

“I’m out.”

They pack their things, close their laptop, and physically remove themselves from your reality. If they’re leaving the company, they’re probably heading to their farewell drinks while you sit there blinking at the code abyss they left behind.

No Slack messages, no email replies — just a legacy system and your shattered optimism.

Code Purgatory

You sit in stunned silence, staring at the screen.

The code doesn’t make sense. The comments contradict each other. Half the functions have names that look like someone banged their keyboard in frustration. You see a TODO from 2017.

And then you find it, the comment that explains what is going on:

In my case for both the TODO and the comment above in one particular company I was not empowered to remove them. The reason I got was that “sometimes comments are useful”, and while I agree with that sentiment obviously it doesn’t really make sense in this context.

I think back to that time I received a Slack message that fully communicated the mess I got into.

Congratulations! You are now the owner of the code.

Why Are Handovers Always This Bad?

I want to put malpractice to one side. Handovers shouldn't be that bad, and here is why they are so poor overall.

Developers Don’t Like Writing Documentation

Let’s be honest. Most of us would rather refactor an entire monolith than write documentation. The best you’ll get is an outdated Confluence page and a README that just says:

Run setup.sh

The script doesn’t work. You use blame to check who wrote this comment. You find that Bob left two years ago.

Last-Minute Knowledge Dumps Are Useless

No matter how brilliant a developer is, explaining six months of development in a one-hour handover meeting is an impossible task.

Asking if you have any questions at the end of that one hour doesn’t count as interaction or engagement.

If you think that you’re hearing the verbose equivalent of “Yeah, so basically, it’s just a bunch of if statements”…you are.

A good handover takes planning, thought and delivery. Just closing your eyes and hoping simply is not enough.

Everyone Thinks Their Code Is Self-Explanatory

Protip: It never is.

If code was truly self-explanatory, we wouldn’t have entire teams dedicated to figuring out what the hell is going on in old systems.

Just saying. If only more people listened to me at work perhaps, we would be able to change this.

The “Not My Problem” Mindset

Let’s be real.

If you’re leaving a job, you’re probably mentally checked out before there is any sign of a handover.

When the handover actually happens motivation is something that has come and gone. The only thing on the mind of the person delivering the handover is starting their next job or taking a much-needed break.

How to Survive a Code Handover

So, you’ve inherited someone else’s code? Here’s how to minimize the suffering:

Assume Nothing Works Correctly

Even if they say, “It’s stable,” they are lying.

Version Control Is Your Best Friend

Git blame will tell you who wrote the nonsense you’re looking at. Unfortunately, it won’t tell you why.

Ask as Many Questions as Possible (Before They Escape)

They may try to dodge them, but if you ask early, you might get some vague answers before they vanish.

Find the Sacred Knowledge Keepers

There’s always one person left behind who somehow knows the ancient secrets of the system. Befriend them. Bribe them with coffee. Your survival depends on it.

When in Doubt, Start Over (If You Can)

If the code is too cursed, sometimes rewriting from scratch is less painful than untangling someone else’s spaghetti. But good luck convincing management of that.

Conclusion

If you ever have to do a handover, don’t be that guy.

Write a few docs. Do a proper walkthrough. Don’t just dump and run.

But if you are going to dump and run… at least leave some helpful comments. Preferably not:

My Code, Your Problem Now!