New job, new codebase. How do you even get started?

One of my readers asked:

How do you get started when you join a new company? How do you add features to a codebase that is massive, scary, and completely new to you?

The first day at your new developer job is just like the first day at a new school. 🚸

A sea of stranger's faces watching your every move. Unfamiliar smells in the hallway.

Every chair is uncomfortable and makes weird noises when you sit. "Eek, there's chewed-up gum under the seat!"

The cafeteria, as expected, serves undrinkable coffee.

Just like the first zoom meeting with your new team.

Are they friendly and cool people? Will they think your code sucks?
What about that Github link they've just sent you? Urgh, look at all that foreign code!

Your first day at your new job can be quite scary.

But what if you could feel confident, supported, respected, and comfortable collaborating with your new team?

What if you knew how to find your way around any codebase?

What if you could be so focused and productive that you don't even notice time passing? Your working day goes like a breeze!

After you read this post, you will know what strategies to use so you feel comfortable and know exactly how and where to get started 🌟

Before You Join, Take Time Off

This might not be possible in every situation. Do your best to take some time for yourself.

Take some time off before you start at a new job. Two weeks at the very least. Take this opportunity to start fresh and spend a couple of weeks relaxing and clearing your head.

Having this extra headspace will help on your first week as you learn new things and get to know your teammates.

The reason you feel so tired on your first week even has a scientific name: it's called Acculturation. It's hard for anyone.

Companies might try to pressure you into starting as soon as possible, but it's always your choice.
Assertive communication and taking care of yourself are qualities of a confident software engineer.

Ask for Onboarding Materials or Documentation

Ask if the company has any kind of onboarding materials you can look at the day before you join.
Try to learn more about the stack, the codebase, and how the team works.

For a startup, it's always good to look at their pitch deck so you can understand the problem they are solving and what kind of customers they are serving.

Some companies won't be able to share anything with you before your first day for confidential or security reasons, while others might.

In the past, one of my colleagues was given access to our codebase and got paid to work on it as part of the interview, which is a very neat way to get people onboarded more easily.

Onboarding Buddy

When the company has some form of onboarding process plus good documentation, it makes things so much easier. Take advantage of it.

Having an onboarding buddy helps a lot in your first few weeks, as you get to know your team, the company's culture, how the product helps customers, and how people collaborate.

Having someone to talk to and support you on your first week is very important.

This onboarding buddy should also help you set up your dev environment. If there's no onboarding process in place, you can always ask for an onboarding buddy. Help them understand the value of good onboarding and get the ball rolling.

I've managed the onboarding process for one of my past employers and we've onboarded dozens of software engineers. Every one of them said that having a good onboarding process made them feel much more confident, welcomed, and productive.

If there's no go-to person to ask your questions, or you don't feel comfortable asking for someone to help you in your first few weeks, read on. There are a couple of other things you can try.

Update the documentation and onboarding materials (optional)

When you are getting started, it's always good to update the documentation being used for onboarding. It's often out-of-date, so it's a good opportunity to make things better for yourself
and your team in the future.

That's an easy way to show your peers you are a team player and you are committed to making things better for everyone.

Issues and Feature Requests: Make Sure You Understand Them

First and foremost, you have to understand what a new feature is supposed to do, and what would it mean for it to be "done and complete." Teams often have different interpretations of done.

For some, 'done' means 'tested and shipped to production'. Other times it just means 'ready for QA'.

Work with the person that created the issue or
feature request to make sure you understand it well.

Not every team is good at writing and explaining things well on paper. Trying to understand what you need to do just by looking at the issue description or feature request can be challenging. You will be missing a lot of context as a new member of the team.

Don't be afraid to ask questions if you're not sure what needs to be done, and take notes. Updating the issue/feature description always helps.

Write well, be kind to your future self.

I love writing good and descriptive user stories even if it's just for me to read. They help me a lot a week from now when I don't even remember what I'm supposed to build. Happens all the time. 🤷‍♂️

Latest Merged Pull Requests: A Gold Mine of Information

After trying the usual stuff such as looking at the documentation and potentially outdated READMEs, you can move on to the next step:

Look at the latest merged Pull Requests

One thing that helps the most is going through the latest merged pull requests and seeing what happened and how they look.

This is the best way to see how people approach building new features on your team. Pull Requests usually have linked issues or feature requests you can read as well.

This shows which parts/modules/classes/files in the system usually need to be changed in order to ship feature X or Y.

For example: let's say the latest PR shipped the orders endpoint.

You look at the diff, you might see this:

• a new database migration
• a new model
• a new controller
• a new policy
• changes to the routes.rb file
• a new serializer and/or views
• new tests: feature tests, request tests, model tests, etc.
• a new factory
• documentation updates
• etc.

Sometimes a feature touches infrastructure code as well (terraform files, CI stuff). Some teams ship database migrations in a separate PR.

Looking at the diff/code changes helps you see what needs to be done.

Collaboration

You will also get a sense of how the team works.

For example, you might get answers to these technical aspects:

• How much test coverage is good enough?
• What's the coding style people follow?
• What are the conventions and best practices being followed?
• Which libraries are being used?
• Which patterns are being used and how code is organized?
• Do people open large Pull Requests or small ones?
• Do people split changes into frontend and backend changes?
• Is the project organized as a monorepo or a multi-repo?
• How does the CI/CD look like?
• How code gets deployed (manual vs automated deployments)?
• How and when do database migrations get merged?
• Does the team refactor code and pay down technical debt? When?

You will learn how people give feedback. How much do they nitpick on the small stuff. How much bikeshedding is allowed.
How technical discussions are conducted.

Some teams care about good architecture and design. Others like to do incremental changes, refactoring, and paying down technical debt when needed.
While others don't really care about any of this stuff and prefer to move fast and break things.

These are useful things to know and expect when you submit your first PR. That will give you more confidence.

Take a peek at routes.rb

One simple trick is to look at config/routes.rb first.
Routes give you a sense of the endpoints and features that are available without having to go too deep into the codebase.

By looking at the routes, you will know if the project has an external API or not, which is very useful information.

Read Related Code

Take a look at code related to the feature you're working on. Models, Controllers, and the Schema or related migrations are good places to look.

Let the Team Help You: Submit Your PR and Ask for Feedback

Your new team wants you to be successful. That's why they hired you in the first place: because you're a great developer and you kick ass!

Let them help you be successful.

You can always submit your PR as is and wait for feedback. Let people help you finish it. You'll never know everything up front, there's no point in trying to make it
perfect on the first try.

If you get stuck, ask for help. Let people help you! There's no shame in that.

Remember to add enough context in the Pull Request description so people can understand what you are trying to do.

How to receive feedback

Constructive feedback is always valuable. Listening to constructive criticism is how you learn and get better.

Ask: what can I learn from the feedback I've received?

Ask questions so you can understand their point of view. Be curious and open-minded.

Don't worry too much if people request changes or point to you things that could be improved. Don't be afraid to make mistakes.

Ask: did I add enough context in the Pull Request description?

Sometimes they don't have enough context into what you are doing. In that case, add more context to help them.

Sometimes they have a point and they are right. Be flexible and open, as they are giving you feedback so the team can ship good code. They could be asking you to follow some of the team's conventions that you might not know of.

Other times, the reviewer just thinks differently than you. This is also fine. No two developers would ever write code in the same manner or style all the time. For these types of requests for change, you can politely disagree.

With time you will learn how to separate changes that are "nice to have" but don't make any real difference, and changes that are really important.

Having integrity and being assertive are hallmarks of a confident coder. Be graceful when receiving feedback. Even if people do criticize you for no good reason, don't take it personally.

Be kind, be gentle, and remember: your work does not define your value as a person.

Asking questions is an effective way to change your approach to receiving criticism. By asking a question, you stop judging yourself or others, and you start to be more curious.

The Confident Developer Onboarding Checklist

Here's a quick checklist you can use for self-onboarding ✅

• [ ] Ask for some time off before I start
• [ ] Ask for documentation or onboarding materials
• [ ] Take advantage of the onboarding process
• [ ] Find an onboarding buddy
• [ ] Understand the issue or feature request I'm working on
• [ ] Look at the latest merged Pull Requests
• [ ] Take a peek at the routes.rb file, or any code related to my work
• [ ] Let the team help me
• [ ] Get out of code perfectionism paralysis
• [ ] Ask for feedback
• [ ] Learn from the received feedback

If you have other ideas that helped you in the past and want me to add them here, please let me know! 💡

---

Hope you apply these strategies to give you more confidence in your first few weeks at your new developer job.

Print your checklist and don't forget to use it! Bookmark this post and share it with any friends who need to read this ⭐

Before I forget: congratulations on getting a new job, that's awesome! I wish you all the best!

---

Do you want to become an expert developer?

I write about how to build expertise on the hexdevs newsletter. We do live-coding and live stream events with some software industry experts. Sign up and be the first to hear about it.

Comments

[Masroor Hussain]

Thanks for compiling this helpful article!
Another very helpful thing which one can do is to generate an ERD(Entity Relationship Diagram) for the project(considering that it's SQL based). This can be easily done using a gem which will extract the ERD with relationships and attributes of all the ActiveRecord models being used in the project.
Here is the gem

Best of luck!

[Thiago Araujo]

you're right, ERDs are really useful, specially on larger projects. Thanks for the suggestion!

[Thiago Araujo]

That's a good strategy, I do that as well!

Most codebases have some form of a "user" model, and this is often one of the oldest classes. It tends to accrue some technical debt naturally.

It's a good place to look at when you want to do some digging and learn more about the history of a project.

[Yaroslav Shmarov]

Very good intro into what to look at when you are given access to a repo!

I always start by looking at:

• Gemfile
• package.json
• schema.rb/structure.sql
• routes.rb

[Thiago Araujo]

Great strategy! I often look at the schema and the models directory as well.
Thanks for sharing!