In previous two instalments of this series, we covered the research part and the creation of an ETL pipeline using Singer. In...
How we handed over the My Viking project to the Mobile Vikings team: 5 essential tips to successfully transfer a codebaseYakup Kalin
As you might have read in one of our previous posts, we recently helped the Belgian virtual network operator Mobile Vikings launch its totally renewed My Viking app to over 270.000 users.
Months after this first big launch, we’re thrilled to see the app still serving thousands of Vikings very well. When we first started this consultancy project for Mobile Vikings, we had several goals. Some of them were:
- understanding the needs of the Vikings (users) and Mobile Vikings;
- developing a new cross platform Mobile app and provide the best mobile app experience for the Vikings;
- helping Mobile Vikings phase out their previous mobile app and phase in the newly developed app;
- creating a high quality, scalable, documented and clean codebase for a low-threshold developer onboarding and a solid kickstart for Mobile Vikings with a solid codebase;
- facilitating and performing a complete project handover when the time is right.
In this blog post, we’ll focus on #5, the My Viking project’s handover. Below we’ve listed 5 essential tips you can use as a checklist on how to successfully transfer a codebase. Transferring a codebase touches on numerous processes such as development, testing, deployment, project management, maintenance, and documentation, so let’s get started!
1. Provide enough documentation and information
We’ll start with documentation since it’s one of the key aspects that define a good codebase. Without any (proper) documentation, the onboarding of a new developer will be a nightmare. Imagine visiting a city for the first time without a map. Chances are high you’ll end up lost and frustrated. This is the same for codebases without (proper) documentation. New developers need to analyze most parts of the codebase to understand it. This will be time-consuming and in most cases annoying if there isn’t any proper documentation.
That’s why providing documentation is the #1 item on this checklist. Documentation consists of several aspects:
- Self-documenting code: the code should speak for itself. It needs to be easy to read and understand. Following consistent and clear naming conventions for example can reduce the need for developers to consult secondary documentation resources such as code comments or manuals.
- Project setup and structure documentation: when you create and setup a project from scratch, you make certain choices. Choices concerning frameworks, libraries, tools and a specific folder structure for example. Documenting the choices and the rationale behind those choices will make the life of an onboarding developer a lot easier. It will help new developers understand, revisit or challenge the chosen tools or frameworks more easily.
- App architecture documentation: the documentation of the app architecture is mainly important to give architectural insights concerning the different layers within the app. It visualizes the storage strategy, usage of external (third party) libraries, the authentication method used within the app and so on. A diagram is a good choice to easily document and visualize the app architecture, and will be the blueprint of your app.
- Known issues documentation: during the development of a project, you inevitably encounter small and big issues. You might think that the ones you solve typically won’t introduce any harm anymore later on. However, new developers might not be aware of the version bump of that one library you did to avoid an issue. And therefore they probably won’t keep it in mind during the whole development process. Documenting known or potential issues is crucial, and will help the new developers to avoid pitfalls.
- Build process (Continuous Delivery) documentation: A black box mobile build process won’t help any developer in the long term. Especially if you have an extensive automated build process covering steps such as environment prepping, certificate and key retrieval for signing, project building, app signing and (test) distribution. It can be very complex and a pain in the a**. Thoroughly documenting every step of this process is the wise thing to do, since issues in one step can have very frustrating and difficult to solve problems in later steps.
2. Introduce a time of overlap with the fading-in team
Imagine a construction worker who’s asked to help build a new house. The construction is past its first stages, but the initial workers are no longer available (e.g. sick or fired) and our construction worker needs to take over. Sounds great right? Exactly.
That’s why we need to talk about the importance of introducing a time of overlap during a project handover. You could look into the documentation (see tip #1) to gain valuable knowledge about the codebase. But unfortunately that by itself doesn’t suffice. A newly-onboarded developer will miss project insights, code and architectural alignment and the ability to directly ask technical or functional questions.
Don’t underestimate the importance of time of overlap! A time of overlap will save you a lot of phone calls and emails during the onboarding of the project.
A time of overlap eases the onboarding of any new developers. The feedback loop is shorter, potential assumptions can be quickly validated and there’s instant support. Additionally, newly-onboarded developers usually work at a somewhat slower pace since they need to get familiar with the codebase first. Having a time of overlap plays a crucial role in getting new devs up to speed as fast as possible.
3. Let new developers perform code reviews
Personally, one of my favorite aspects during a project handover: code reviews by the new developers. This step won’t only help the new developer audit the code, but it will also introduce potential fresh insights. Other developers might have been embracing other design patterns and/or technical approaches. This can trigger interesting technical discussions, helping you to improve the code quality even further.
Code reviews also elevate knowledge transfer between developers (and teams) and give the new developers crucial architectural insights. At ACA, we always code review every line of code that the developer wants to be a part of the codebase. Developers reviewing the code can add comments on those lines to ask questions or highlight potential issues. The code review happens on a chat-like interface that’s on top of our code repository.
If you’re interested in integrating this code review process within your own development cycle, shoot us an email. We will be glad to give you detailed insights and help you set it up!
Help me set up easy code review
4. Have new devs implement small things and run the project
Instead of letting the new developers directly jumping into new big features, it’ll definitely be a better idea to let them work on (relatively) small changes and features. This way they’ll be more confident in introducing changes or new code within the codebase later on. Additionally, since the changes or features are smaller, the impact of potential mistakes on the codebase are limited, more isolated and easier to control.
Asking the new developers to join a sprint and implement (small) features also encourages them to experience the agile development cycle end to end. From the intake of the user story all the way until its validation. That means new devs have to build and run the mobile project on their development machine, validating the environment variables and setup on their machine that are required to build the software.
5. Discuss the scope status and the next steps
Last but definitely not least is demystifying the current scope status and the next steps. Not only does this introduce a common understanding within the team, it also creates alignment concerning the roadmap and priorities.
At ACA, we facilitate this by using Atlassian’s Jira for our project management. Jira allowed us to easily visualize and create reports concerning
- the work that was completed,
- still in progress,
- or waiting in the to-do list (MVP-x and backlog).
If you’re interested in gaining full control over your projects and the ability of e.g. creating scope reports, feel free to contact us. We’ll be glad to give you more insights regarding Jira and help you set it up.
Our Atlassian services
Key benefits and takeaways
As we considered these 5 crucial aspects mentioned above, during our Mobile Vikings My Viking app project handover, we were able to:
- get the new developers of Mobile Vikings familiar and comfortable with the codebase,
- explain and discuss the architectural setup and choices more easily and efficiently,
- and create a common understanding and alignment between the teams.
In the end, these practices facilitated a solid codebase and knowledge transfer.
We believe the 5 practices listed above are crucial tips that will help you transfer a codebase with ease. For the sake of good order, let’s sum up these 5 tips again:
- Provide enough documentation and information
- Introduce a time of overlap with the fading in team
- Let the new developers perform code reviews
- Have them implement small things and run the project
- Discuss the scope status and the next steps
If you have any questions regarding some of those tips, we’d be pumped to answer them for you! Leave us a comment down below or email us and we’ll get back to you ASAP.
See how we developed the My Viking app