Whether you're just starting out as a developer or you've got years under your belt, learning a new codebase is a defining experience.

Onboarding shapes not only your enjoyment of that project but can influence what sort of work you go on to do next. Either you're running screaming in the opposite direction, or you've found something you want to do again.

For every codebase onboarding that feels like an effortless walk in a sunny meadow, there are plenty more that evoke a 3am hike up an unlit rocky path during a hurricane.

Below is an inexhaustive collection of postcard-sized onboarding stories from real developers. They illustrate some of the specific ways in which onboarding can go wrong, and, at the end, there's a hint at one way we might make it better for the developers who come after us. Names have been changed.

I've suffered, so shall you

If a problem shared really is a problem halved, then perhaps that explains what happened to Mark.

The first day on the job, the incumbent developer asked a question, "How do you feel about spaghetti code?" Not leaving any time to answer, he followed up with, "Because what we have here is code soup."

The product should have been straightforward. It was a web front end to research data held in a PostgreSQL database. However, Mark was the fourth developer to work on the system in a short period of time. It was almost as though each prior developer had gone out of their way to avoid any consistency with their predecessor. Instead, they picked the tools and conventions they preferred. That led to fun situations such as Hibernate taking care of user and project records, while JDBC was used for general querying. As Mark says, "Why have one data abstraction layer when you can have two?"

Sure, the codebase itself was a mess, but the onboarding was essentially a surrender. "I know this is terrible, but I've suffered, so that means you should too," probably isn't the ideal onboarding maxim.

Mismatched expectations

Starting a new job is somewhat stressful, even in ideal circumstances. There's the pressure to show your best in those 30-60-90 reviews and to win round your new colleagues.

But for Gavin, a Python developer, starting one job, in particular, was especially fraught. "They knew I wasn't a Ruby developer but somehow also expected that I did know Ruby."

On top of learning the new codebase, Gavin also had to learn a new language. Not an impossible task but also one that no one at the company had made allowances for. "They pointed me at rubykoans.com and wished me well. The Koans are good, but they don't cover de facto essential stuff like Rails," Gavin said. After years in the Python ecosystem, he also found that the difference in approach between Python and Ruby docs took some getting used to.

For Gavin, it was the shock of the mismatched expectations, combined with his own desire to show his best work, that made this particular onboarding hard. "One person's experience of learning new tech can be worlds apart from your own: I was joining a company of Ruby enthusiasts who probably found it hard to put themselves into my shoes. I had 20 other things competing for my time and attention, as well as that huge pressure to be productive. Having to also learn Ruby, Rails, and the special way in which Rails was used at that company, before being able to be productive was very stressful. I came close to quitting or being fired."

Why can't you just understand?!

There are situations where a problem space is just plain hard. Some things take time to understand fully. But other times, it's not the problem that's hard to understand, it's more that the person getting you up to speed lacks the necessary empathy.

One developer, Gráinne, found that the person onboarding her was perhaps too close to the code to see it from a newcomer's point of view.

"On my first day, I showed up, got access to the code, and then had a two-hour sit down with the CTO. He was also the architect of the product and the lead developer. The trouble was that he talked very fast and got quite exasperated when you didn't immediately understand what he was saying."

For Gráinne that meant making whatever notes she could during the onboarding/interrogation and then trying to fill in the gaps by reading the code.

But even past the onboarding itself, a Monday morning could put things back to square one, "The CTO would often, over a weekend, massively change huge chunks of the code, breaking things in horrible ways, and then would shout about it until we fixed the mess."

We are unreliable narrators

Perhaps there's a theme that unites all of these stories: bad developer onboarding happens when there's no process or a process that fails to take account of people's different expectations and approaches.

Jeroen, a developer for a large multinational, put it this way, "Much of what we do in our business is communication. When we communicate, we're always referring to knowledge in our heads that we hope or assume is also present in the other party's head."

The problem is that it's hard for us to understand where that shared frame of reference ends and where we need to teach something completely new. Gráinne's CTO became frustrated when other people didn't understand his explanations because he couldn't imagine that other people had different experiences to his own.

Yes, we can grow as teachers and communicators. But there's a deeper issue. Onboarding shouldn't be an oral tradition.

Codebase onboarding as oral tradition

Let's take a moment to imagine something different.

You're sat around a fire with your family and close friends. The day has gone well. There is food, you have shelter, and yet there's a threat.

Some of the younger children have been wandering into the woods and eating mushrooms. Most have been fine, but one or two have become seriously ill.

You want to protect the children, but they don't understand why some mushrooms are bad, and others are just really tasty. You don't even know yourself. So, you tell a story to put it in a context you can all understand. You think on your feet. One of the elder members of your village can tell good mushrooms from bad. So, you say that all mushrooms have an evil spirit that only old people can cast out.

The story works. Over the years, it gets retold and embellished. Eventually, there's so much mythos around mushrooms that the original intent of the stories becomes forgotten. Even so, somehow, it continues to protect people, despite there now being a lot of unnecessary ritual associated with preparing mushroom-based meals.

Stories passed by word of mouth work act as vehicles for important knowledge. And we still use stories in our work as software developers.

Onboarding is a documentation problem

When everything is urgent, it's hard to prioritize work that will help you in the future. So it's somewhat understandable why onboarding a new colleague can be haphazard, clumsy, and inconsistent.

However, a bad onboarding is often actually a symptom of other problems. One particular issue is simply that many codebases lack good documentation. While individuals methods might have excellent comments, perhaps understanding of the whole system is less well documented. For example, there are teams where no two members would draw the same architecture diagram despite working on the same product.

At CodeSee, they've built tools that make it easier for teams to onboard new developers. And that's not by doing special extra work that just gets used in onboarding. It's by creating a shared understanding that benefits everyone who works on a codebase from onboarding and for the long term.

Regretful man photo by Nipan Chawcharernpon
Spaghetti by Maurijn Pach
Pomegranate seeds by by Tima Miroshnichenko
Angry cat by Pixabay
Scrabble tiles by Kathy Jones
Campfire by Jens Mahnke