Simon Harriyott

How to add new developers to a team

When a developer joins a team, they need to become familiar with the codebase. It can seem a daunting task, but it will happen somehow. There are many approaches, with various levels of planning. There's no single right way, and different teams and developers should choose their own path. Here are some examples:

  1. A comprehensive induction training programme
  2. Reading a set of documents
  3. On-going mentoring and pair-programming (as suggested many years ago by a talented young developer )
  4. Working on hefty changes with initial discussions and pair-documentation with an experienced developer, and regular feed-back sessions
  5. Working on small, discrete bug fixes or features, asking for help from an experienced developer as required
  6. Reading the codebase, and stepping through it with a debugger to watch the process flow through the application
  7. Reading completed cards in the issue tracker, and the code releases that implemented them.
  8. Using the front-end, either guided or experimentally, to understand how the components of the system interact
  9. Discussing the system with established end-users and business analysts to glean the motivations and impact of various features
  10. Gradual assimilation of information from overhearing conversations, being copied into email chains, listening to daily stand-ups, reading pull requests etc.
  11. Piece together understanding of the system unaided through various methods the new developer finds personally effective
  12. Giving new developers greenfield projects to postpone or avoid the issue altogether.

This isn't an exhaustive list. I've sorted it roughly according to how much preparation is required. There's a scale, which I shall pompously call Harriyott's Scale Of Onboarding Preparation, or SOOP. One end is fully prepared, and the other is fully reactive.

Fully Prepared

It's easy to assume the fully prepared end of the scale is the best end. After all, failing to plan is planning to flail. The new developer will have everything they need to understand the codebase, and be able to safely contribute. For very large teams, a training programme can be an efficient way to introduce a sizable influx of developers to the project. It can also create a good impression with the new developers, that they have joined a well-managed team.

It's not all butter and teapots though. It takes time to create a training programme, or comprehensive documentation. Most of the work will be done by the existing programmers, which means they won't be writing new code. The skills required are different to writing code, so the programmers may struggle to produce high quality materials, or be resistant to spending time on non-coding activities. If there is only one developer joining, it may be a hugely inefficient process.

There's no guarantee that it will be useful either. The new developer may not favour learning from a large set of documents. They might learn better from watching videos of conversations between developers, or by rooting around in the code itself.

The developer may learn about one area of the system, but not work on it for a year or two. It may be stable, and there are no feature requests or bug reports that enter that area. The time writing the materials was wasted, along with the time spent by the new developer reading them.

The more time is spent on this, the longer it is until the developer starts contributing code, which is expensive.

Fully Reactive

At the other end of the SOOP is very little preparation. The existing developers are fully productive fulfilling the needs of the business, and the status quo is maintained. The new developer is dropped in the deep end and has to sink or swim. 

It can be a lonely time joining a new team. Without active support, the new developer may feel bad for interrupting the “important” developers, or not want to look stupid by asking too many questions. They may decide to undertake their own research, which would take considerably more time than had they just asked. Their research may not be accurate or complete. They may not grasp the context of the bug they are fixing, and then introduce regression bugs. This leads to more rework in code reviews, and a drop in confidence.

When they start a new piece of work, they have a new subsystem to learn, or be taught. This won't have been planned for, and will require either self-learning time or support from an existing developer.

Although the existing developers understand the newbie's predicament, they are frustrated by the interruptions, because it affects their concentration, and their deadlines. They may become resentful.

The result might be that newer developers are kept away from the existing developers, and given low priority work. It seems like a way of protecting the existing developers, but it delays the efficacy of the new developer, which is expensive. They may be put on greenfield projects instead. Again, it protects the existing developers, but they may be resentful that they aren't getting the fun jobs.

It's not all teapots and butter though. No time is wasted producing documentation that isn't read, or becomes out of date, or doesn't actually help the new developers. The new developers can start working on the system immediately, and experience the code and quickly see their work in the hands of the users. They'll only know what they need to know at the time. Many developers learn better by doing, and over time they'll have a complete picture of the system through exposure.

The Balance

Generally, without intervention, a team drifts towards the reactive end of the SOOP. Some decisions make themselves. This isn't necessarily a good or bad thing, but the team needs to understand the consequences, and be prepared to deal with them. If the decision is to avoid pair-programming, then the consequence will be intermittent questioning. This should be supported, as it was what the team (maybe inadvertently) decided would happen.

Conversations are needed from the moment the team decides to recruit a new developer. The existing developers should be asked how they want to be involved, and time allocated for them to do a good job. When interviewing candidates, ask them how they like to learn, and how they best get up to speed. If it is completely different to how the existing team works, then maybe they aren't right for the job. 

As with many things, the way that developers are happiest working is the way that developers are the most productive. Unhappy developers have a habit of leaving. 

As For Me

Having been a contractor, I've been the new developer many times. I've found that I like to get to the code early on. I appreciate a quick overview of the company as a whole, meeting the stakeholders, and a brief tour of the UI. 

I like a nice set of instructions for getting my machine set up so I can run a local version of the code. 

My first piece of work is ideally a simple premise that touches all the layers of the system. Adding a text box to an existing form which is saved to the database is ideal. I don't need to understand complex business requirements, and I experience a lot of the codebase in one go. It's easy to follow the path of other text boxes on the form, so I get to see how the layers are set up, where the repositories are, how database scripts are generated and run, how the UI is built, and how the front-end talks to the server. 

Once I've done a couple of those, I've pretty much learnt the basics, and can move on to some meatier problems. I'd only have the problem itself to worry about, and I'd be able to see where to put each part of it.

I don't like to read a lot of detailed documentation. My first week at one job was spent entirely on reading. Most of it didn't sink in. It was comprehensive and dry, and I didn't understand how it was relevant to me. It was only once I started coding that I could ask some questions and begin to understand how things worked. 

The documentation I would like to see, but never have, would be a video of a previous new starter talking through the codebase with an experienced developer. These conversations are always the most revealing, and contain the good stuff that never makes it to the actual documents. “Oh, Terry added that module for the SpoonFeed client, but the other clients each wanted something different, which is why there are so many method overloads”

I've been the experienced developer too. I don't recall ever being given much time to prepare in advance for new starters. I like sitting with them and chatting through the main areas of the codebase, and giving them tasks to do. I like answering questions, and enjoy being helpful. I like making my new colleagues feel welcome, and it's a good way to feel like part of a team. 

I was once made redundant with four months notice. Our office was being closed, and the work outsourced to Bulgaria. It was my job to write handover documentation. It was horrible. I wasn't told what kind of documentation, just what was needed for the new team to pick it up. I didn't know what that was. I'd look at a section of code, and wonder if the comments explained it enough, or whether I had to write about each method in the documentation. I didn't know how much of the business processes I had to explain to put the code into context. I resigned and started contracting. I forwent my redundancy pay.

As For The Experts

Brooks' Law: “adding manpower to a late software project makes it later”. From 1975, and still true. It's not reassuring, but useful for planning. Accepting this, and gaining management approval for the delays in advance, makes for a happier process.

The Manifesto for Agile Software Development: “... we have come to value ... working software over comprehensive documentation”. So have I. Also, in their principles:
“The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”

Chesterton's fence: “Reforms should not be made until the reasoning behind the existing state of affairs is understood”. In this context, don't have a new developer work on a massive feature in a legacy codebase until they know how it works.


There are many ways to introduce developers to a team. Make sure everyone is happy with the plan.

16 May 2020