Optimise your code for a better onboarding experience

Raquel Velez looks at how an onboarding-focused approach to development can help get new coders started as efficiently as possible

Your newest teammate has just pulled the codebase onto their machine for
the first time. Unfortunately for them, everyone is away at meetings and won’t be available to answer questions until the end of the week. Now what?

When someone joins a team, they already need to deal with HR and get to know their new teammates. Add to that the daunting nature of learning a new codebase, and the first several weeks on a new team are difficult at best.

It’s in everyone’s favour to optimise the onboarding process. From a financial perspective, every minute a developer isn’t contributing code is costly. From a developer’s perspective, every minute they’re not shipping code is unproductive.

So how do we make onboarding more effective in less time? Let’s do what we always do: let’s look at the code.

Application structure

Look at how your codebase is structured. Could you send your file tree to another developer (who does not work with you … that would be cheating), and have them tell you how the application works?

Codebases are in a constant state of disarray. The code you write today will be refactored eventually. Therefore, as you’re working through your application, anticipate your next teammate and ask yourself: what can we do, on an architectural level, to ease someone in?

Start by using well-named folders that clearly explain what they’re for. Avoid the dreaded ‘util’ file at all costs. Make it explicitly clear where the code lives, so when someone starts hunting around, they’re spending more time thinking about how a chunk of code works and less about where it lives.

The code you write today will be refactored eventually. Ask yourself: what can we do, on an architectural level, to ease the next person in?

Tests

How much of your codebase is adequately tested? Do all your tests pass? Do you name your tests? In other words: can someone run your test suite and immediately know what your application is supposed to do?

When a newcomer joins the codebase, one of the first things they’ll need to do is run the tests. When they get to the point where they’re fixing a bug or adding a new feature, you want them to find out as soon as possible if they are breaking other parts of the application.

Write your tests so someone can run them and read what is supposed to happen as the application runs. This way your new team member will be able to understand what the code is already doing, allowing them to ask more complex questions about the rationale behind it.

Documentation

Are you confident that the documentation around your code is sufficient? In particular, does your documentation cover interdependent codebases? No matter the size of your team or application, there will always be code that depends on the output of some other code.

Reduce the number of questions about how functions work by clearly documenting what each function does, what parameters it takes, and what the output of that function is. To make it easier for someone to understand what each chunk of code does, embrace the ‘many small modules’ approach to writing code. Allow for abstraction at high levels, but be clear under the hood how everything works. You can’t know which part of the codebase your next team member will be working on, so prepare it for anyone.

Above all else, make sure the documentation is easy to find. You want everyone on your team to be able to find the answers to their questions with ease.

Let’s do this

We’re used to thinking about the user when we create our products. But what if we consider the newest member of our team as we build our codebases? The best teams share an understanding of where each
bit of code lives, what it does, and why. They can then spend their time discussing how that code should work. Working on ‘how’ instead of ‘where’ , ‘what’ or ‘why’ is essential to productivity.

In short, we need to acknowledge the reality: we are not the only ones looking at our code, and one day we won’t touch it at all. Let’s consider those who are picking up the pieces after we’re done with them, and make it as easy as possible for them to ramp up, as quickly as possible.

Raquel Vélez is crafty about code and culture at npm, Inc. She also enjoys adorable animals, funny GIFs, and chocolate

This article originally appeared in issue 277 of net magazine