Feb 27, 2025 New Codebase Onboarding Strategies for Efficiently Learning a New Codebase

Harrison Strowd

Jumping into a new codebase can be daunting. Whether you're joining a new team or tackling an unfamiliar project, getting up to speed efficiently is crucial. As a consultant, I've gotten practice joining well-established organizations and have developed some guidelines that help accelerate the learning curve on their systems. While I tend to progress through these steps in the order presented, feel free to adapt the approach based on your needs.

Use the README

The README is generally the best place to start. It provides an overview of the application and essential context. Even if you don't immediately act on the information, it lays a solid foundation for understanding the system.

Here's how to make the most of it:

  • Read the README in its entirety and follow the setup steps it outlines.
  • Fix unclear, outdated, or incorrect information. This is a great way to contribute right away and familiarize yourself with the software development lifecycle (code reviews, approvals, merging, etc.).
  • Do some early "boy-scouting". Updating the README benefits future developers and showcases your attention to detail and commitment to continuous improvement.

Build a Mental Model

Understanding the system as a whole will provide context for your work. Seek answers to key questions such as:

  • Who are the end-users?
  • What internal systems and third-party services are used?
  • What are the roles and responsibilities of each component?
  • What data stores exist for runtime and reporting purposes?

If high-level architecture documentation exists, review it. If not, consider creating the following diagrams to solidify your understanding:

  • System Diagram: Identify end-users and applications (internal and external) with their roles and responsibilities.
  • Component Diagram: Document the features/components within the application and their dependencies.
  • Workflow Diagram: Capture the primary user journey, highlighting key actions and decision points.
  • Data Model Diagram: Create an Entity-Relationship Diagram (ERD) to visualize core data models and their relationships.

While these diagrams will benefit the team as a whole, the real value lies in the deep understanding you gain by creating them.

Not sure where to start in crafting these diagrams? Reach out and we can provide some examples from our personal/internal projects or guidance for your specific case.

Learn to Test the Application

Hands-on experience is invaluable when familiarizing yourself with a new codebase. Start testing the application by:

  • Walking through the end-user journey if the application has a frontend.
  • Sending test API requests to simulate workflows.
  • Exercising the system's features that you'll be responsible for (e.g., triggering background jobs, running integration tests).
  • Shadowing engineers or QA team members to gain insights into testing processes.
  • Over-testing your changes early on to catch potential bugs in your local environment.

This investment of time will pay off as you begin making functional changes with confidence.

Extend Engineering Utilities

Building and improving engineering utilities will benefit both you and your teammates while accelerating your onboarding. Depending on existing team tools, consider:

  • Creating a Postman or Paw collection of test API requests.
  • Extending or organizing existing test request collections.
  • Filling in gaps in unit or integration test coverage.
  • Improving reporting dashboards for the areas you'll be working in.
  • Adding or improving documentation (e.g., glossary, getting started guide, etc.).

These initiatives can be self-directed, giving you hands-on experience while providing immediate value to your team.

Find an Area to Go Deep

Once you have a solid grasp of the system, it's time to specialize. Work with your manager or teammates to identify a moderately complex feature or area with changes or improvements to be made.

  • Choose something substantial enough to involve multiple tasks but manageable within a week or so.
  • Dive deep into this feature, implementing changes and collaborating regularly for feedback.
  • Aim to become the "go-to" person for this area, taking on technical ownership beyond simply completing tasks.

Developing expertise in a specific area allows you to contribute in more impactful ways beyond incremental code changes. As your knowledge grows, you'll also be in a better position to provide insight into the application's architecture and influence the team's technical direction.

What else?

By following these steps, you'll gain a comprehensive understanding of the codebase, contribute meaningful improvements, and set yourself up for long-term success within your team.

Do you have other strategies you follow when getting up to speed on a new codebase? If so, we'd love to hear about them. Drop us a note below, and thanks for reading!

Welcome and Explanation

The Opinion Zone™ is a place for thoughts that Dan, Harrison, and Truman share about what it means to build good software products at a sustainable pace in a calm and helpful environment.
Topics range from how to work well with folks, to software design patterns, to whatever else may be on our minds. We think that advice can be misleading and we try to be careful about how we share our thoughts. We'd love to hear what you think, below.
Leave a comment

Thoughts for our thoughts

We hope you find our writing useful and, perhaps, that it gives you something to think about. We read everything we receive and we'd love to hear from you.