## Limits on the Magic

`npx create-react-app` and `rails new` build magical new projects right out of the box. You know what to expect and can shape these projects to your heart’s desire. It’s every developer’s dream.

More often, though, you’ll work with teams on existing projects that were created well before your time. Unfortunately, acclimating to a new codebase for the first time is scary and is by no means simple.

## My story

I started my development career as a WordPress developer. I was building new sites, troubleshooting existing ones, and learning a lot along the way. Then I had an exciting idea: what if I contributed to the WordPress codebase? I could make a difference!

I went to <a href="https://github.com/WordPress/wordpress-develop" target="_blank">WordPress’s main repository</a> and got stuck almost immediately. “Where do I even begin?” I wondered. I tried getting the repo to run in my local environment but failed miserably. Eventually I joined their official Slack channel and created a few online accounts to collaborate with their core team. But still, contributing to the WordPress core codebase was too overwhelming for me and I eventually gave up.

I’ve come across several existing repos since then and have learned not to give up. And you too, with some grit and the right tools, can successfully adapt to an existing codebase. Let’s open the tool box together and see what’s available.

## Your tools

### Read the documentation

<a href="https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes" target="_blank">READMEs</a>, <a href="https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis" target="_blank">GitHub wikis</a>, documentation sites, and tests are all fantastic forms of documentation. I suggest first starting with the README. This file will typically provide a few steps to setting up the project locally and may also include links to important external documentation.

For more detailed information, you can then move on to any wikis or documentation sites that exist for the project. You can also find useful information in the CONTRIBUTING.md file if the project is open source.

Finally, <a href="https://blog.devgenius.io/creating-good-code-documentation-eaa614cb489f" target="_blank">well-written tests demonstrate how software is expected to function</a>. Take some time to read through the test suite. What do you notice in the names of each test? What can you tell about the purpose of classes, functions, and modules from what is already written about them in the test suite?

### Try everything

Reading documentation is a great first step, but you shouldn’t stop there. At some point, I encourage you to put the docs down and light some things on fire (just not in production, please). As soon as you can get access to your new codebase, clone it to your local environment, create a test branch, and start poking around.

What folders and files do you see? Can you create a user to login with? What happens when you `console.log` the output of a particular function, or when you `puts` the data coming from the API? Run a unit test and break it. <a href="https://youtu.be/dmQaT6IY9vc?t=60" target="_blank">Try everything</a>!

### Grab a ticket and just start coding

Now that you’re familiar with the codebase, snag a ticket and get to work! But please, don’t rush yourself. Take your time, follow the <a href="https://www.codecademy.com/article/tdd-outside-in" target="_blank">principles of test-driven development</a>, and ask for help when needed. As ZEAL engineer Nick Fuller <a href="https://github.com/sarmstead/codestart#nick-fuller" target="_blank">notes</a>, “be ready to spend a chunk of time just exploring how things work. Understand that it's OK to take that time to learn.”

### Ask Lots of Questions

#### Ask Google

Speaking of learning, make sure to do your own research as you run into bugs, error messages, or syntax you are unfamiliar with. Don’t feel like you have to prove anything. Just focus on building an increasingly complete understanding of the code in front of you.

#### Ask a human

After you've done your own digging, make sure to ask a colleague, manager, or mentor for help. Don’t worry about being a bother or feeling annoying. Just ask! I learn exponentially more when I include others in my journey, and I urge you to do the same.

In fact, I asked my team and the tech Twitter community for advice on acclimating to new codebases. <a href="https://github.com/sarmstead/codestart" target="_blank">Read what they wrote</a>—it’s pure gold.

#### Ask a Duck

In addition to getting the right answer, asking questions allows you to validate your understanding. So explain what you know so far about the codebase to an inanimate object like a <a href="https://www.freecodecamp.org/news/rubber-duck-debugging/" target="_blank">rubber duck</a>.

Go through each line of code you’re working through, or simply talk through what you know with the object. The goal here is to hear your understanding out loud to help you identify the gaps in your knowledge.

Of course, if a creepy rubber bath toy isn’t your thing, you could also ask a breathing person to help validate your understanding. Just please don’t squeeze them too hard.

## Off you go!

By reading documentation, lighting some (safe) fires, working on your first ticket, conducting research, and asking lots of questions you can face existing codebases with confidence. And hey, how about you write down a few of the <a href="https://github.com/sarmstead/codestart" target="_blank">insights you have for adapting to existing codebases</a>? I’d love to read and share them!

Photo by Rajvir Kaur on Unsplash