How to build software that’s ready for the handoff

As a leader at a digital agency, I often hear the same question from clients after walking them through a proposal: ‘What happens when you leave the building? How will my engineers be able to take this over and own it?’

This is also a great question for any senior technical leader to ask themselves as they embark on new projects. As you determine an architecture, make foundational choices, and lay the groundwork for a system rewrite or new codebase, it’s important that you keep your succession plan top of mind.

We all know that good software is never truly done: as long as users need it, it will have many keepers, maintainers, builders, and architects growing, scaling, and evolving it and making sure it’s humming along going forward. As a senior technical leader breaking new ground on a new software platform, you want to think a step ahead and build for the inevitable handoff.

Future engineers are also your users

When you’re defining and designing a digital product, you do so in service of the product’s users. Similarly, when you’re writing code you’re going to hand off someday (which is all of it), you do so in service of the code’s users: some number of future, unknown engineers, who are going to have to understand what you built, how you built it, and expand, maintain, and troubleshoot it.

Here are some ways to build software with future engineers in mind.

1. Make lower-risk technology decisions
   When you kick off a new project, keep your existing and future engineering team  in mind –  their skillsets and talents, technology preferences, and existing environments. Does your larger engineering org have preferences for certain tools or languages? Aspirations to learn new ones? If you’re making all the initial tech decisions on a totally greenfield product, choose modern but mainstream languages, frameworks, and best practices, the ones that will be most likely understood by the widest range of developers. Only use riskier, cutting-edge, or unusual technology to get a one-time task done if it will make you more productive (like an extensive, one-time data import).
2. Reduce maintenance burden
   When you’re making decisions about how a product is architected  –  that is, how many and which services and servers will be involved  – think about what sort of maintenance and updates they’ll require and how the team will do that maintenance in the future. Then optimize to reduce that burden as much as possible. For example, if you’re creating a web service, can you do it without spinning up a web server? Anything that can overflow with log files, get hacked, or become sluggish will require attention in the future.
3. Write and review code for maintainability, readability, and extensibility (versus terseness or cleverness)
   Code that engineers can’t understand is code that engineers can’t build on, and will want to throw out and rewrite. When you’re writing code to hand off, stay wary of anything that’s so clever it’s opaque, where function and variable names aren’t expressive and clear, and where the code structure makes it difficult to find what you need.

   Documentation should accompany most changes – even if it’s just a descriptive commit message – and enforce standard code style throughout from the get-go (this is why creating a culture of code review is so important; you keep each other accountable to these standards).

4. Create a smooth on-ramp
   One of the key quality measurements of any code repository is how quickly and easily a new developer can clone it and get the code up and running on their computer. When engineers are your users, your code’s onboarding process is the README. The fewer setup steps there are, the better. When you can, containerize your app’s environment to make it portable and easily reproducible, reducing the number of steps it takes to get it running locally or elsewhere. The ability for any engineer to pick up the project and get productive immediately is critical to the health and upkeep of the project (successful open source project leaders know this in their bones).
5. Build phase one to expand easily to phases two and three
   In many cases, senior leaders will build phase one or a minimum viable product (MVP) to prove out a new platform or service that has a long potential feature roadmap ahead of it ,  but it’s not clear who will build those future iterations. When you’re building for the handoff, you’re building for future engineers and product features.

   When you begin, get as much information about future plans for the product beyond MVP, and make decisions that will lay the groundwork for phases two and three to come to fruition with as little refactoring as possible. Documenting potential implementation of future features, given the MVP, gives future engineers a path forward beyond the handoff date.

As a technical leader, part of your job is to work yourself out of a job and empower your team members to take on ever-more critical efforts as smoothly as possible. Building for the handoff is good practice whether you’re a leader or an individual contributor, but it’s key as you bring up your team members to take on more responsibility.