Navigating a New Codebase and Project: Five Rules for Success
In recent years, I have had the opportunity to join slightly over a dozen projects, each at different stages of completion. As an external contributor, expectations for onboarding are different – where full-time employees have 3 months to ramp up, contract work implies high expertise with high efficiency. By the end of the first month, at least two or three medium-size contributions should be merged in a ready state. By the second month, work on a high impact feature should be underway. This gives you the opportunity to do more in less time. This also reassures business owners that they are getting the results they’re investing in.
I've learned a few rules that may help you to integrate into a project efficiently and provide value early. Everyone has their own preferred method of learning, and what may apply to me may not to you. Nevertheless, if you feel like you can improve this area of your engineering skills, experimenting with alternatives is the only way to find out. If you want to learn how change can impact your adoption, read about team dynamics.
1. Meet the People
Every problem is a people problem, even technical a problem. In order to understand a technical problem, the request needs to be communicated. Do not try to guess what the requirements are: find them, even if you don't fully understand the implications. Make sure that you've identified who has ownership over the area that you're working on and has the capacity and authority to answer your questions. Ambiguity and inefficient communication will slow you down. It may be the case that there is no singular person who can answer your concerns. Even then, identify a source of responsibility. In this sense, technical problems are also people problems. Strengthening your relationship with your team will also have a huge impact down the line.
2. Prepare the Local Environment
Local-first development cuts down feedback loop cycles and reduces friction with dependencies. Provisioning of accounts for network-based development, access to APIs, and CI runs can cumulatively consume hours of your focus and frustrate you with lack of progress. Not every project is local-development friendly; within availability, pick up or negotiate being assigned to a task that can be executed with minimal dependencies. This will give you time to prepare a complete work environment and receive access permissions to other tools, all while familiarizing yourself with the project. If the project doesn’t have full local support and you want to propose improving that area, make sure you’re all up-to-date with data mocking.
3. Ask After Thirty Minutes
Projects with varying engineering practices, or lack thereof, can either aid or hinder comprehension of the application's internal design. Almost inevitably, you'll find bump into modules that are tough to follow. If you find yourself spending more than 30 minutes trying to understand how something works, ask for the relevant documentation or give you an overview. (Lacking documentation? Learn why documentation is important and contribute yourself.) As an experienced engineer, not being able to understand a piece of code is likely related to that section of logic being inherently hard to follow or to require domain knowledge. By asking someone to explain it, you'll be saving everyone time.
4. Start Narrow
Self-contained tasks and scoped bug fixes are great introductions to a project. With the help of your team, select an assignment focused on a specific area of the codebase. Top-level changes to the application and straightforward augmentation of modules are more efficient than updates to core modules. You'll be able to cross-reference the project's practices and apply design patterns laterally while diminishing the probability of introducing bugs related to lack of business logic knowledge. Conversely, deep module changes and wide file changes are likely to take much longer than expected.
5. Specialize Then Expand
Once you’ve found your footing in the project and learned the team’s practices, capitalize on your learnings learned and stay within the same codebase area when possible. By this point, you’re in the third or fourth week of joining, and you should be ready to build a standard-track feature. Document potential improvements, but prioritize project consistency. Afterwards, find the time to assess with the team whether your improvement proposals should be implemented. There may be technical or business reasons behind the current code, or you may have not seen the full picture yet. When you do present your finding later on, **make sure to do it right.**
This standard feature will very likely involve intercepting with the wider module set of the codebase. Inspect those areas of the project and branch out. There may be some waiting time during your main work to pick up a secondary task, and you’ll begin to identify solutions more readily.
“Document potential improvements, but prioritize project consistency.”
Learning a new codebase is a continuous process. Remain focused on what you know, and as you become deepen your understanding of the domain, you’ll be better positioned to make impactful contributions. Mitigate time loss due to blockers and business familiarity. Lean on your team to select work that is self-contained and to learn more about the business. become an expert in a narrow slice of the codebase where you can contribute business value, expanding from the knowledge acquired during your first few weeks.
Engineering goes beyond the technical solution, and it’s also your responsibility to promote efficient work allocation. Finally, each business has their own set of expectations, and none of these rules may be available to your situation. Make sure to establish clear expectations and set conservative result timelines.