DEV Community

Cover image for 10 Tips to Navigate a New Codebase
codemattermedia
codemattermedia

Posted on • Updated on • Originally published at codematter.media

10 Tips to Navigate a New Codebase

Everyone is new to something at some point. When committing to an existing codebase with multiple contributors, you extend upon a foundation of ideas that came before you.

A bedrock of patterns, naming conventions, and ultimately decisions other people made about the software's direction at the time.

The keyword here is time.

Most software engineering teams participate in some form of agile-based methodology. A popular framework known as Scrum is a time-boxed cadence of focused energy on specific goals. They typically last two weeks or longer, based on the team's needs. What do people do with all this time?

Engineering decisions can sometimes lead to messy or unnecessary abstractions.

With little or no test coverage and slim documentation, hidden bugs are just waiting to be discovered by you, or worse - a paying customer.

No one person is to blame, as there are often many cooks in the proverbial kitchen. Maybe a product manager asked for a tweak on a feature shortly before a release, causing some funky code.

Or it's the case you slapped on some band-aid code that a future version of yourself would deal with eventually. Right. Whatever the case, I like to think that everyone tried the best at the time.

Perhaps at some point, you were or are the one building the roots of a project. Good for you! That's a lot of hard work. The decisions made here could have lasting impacts long after you stop contributing. No pressure!

When joining a new team, most engineers will find themselves adding to an existing codebase. Some of that code could be very outdated but still needs to be maintained for a business reason.

You could be dipping into some confusing code that someone threw together because they didn't have enough time.

Or maybe the requirements were sketchy and left out some edge cases that went unnoticed. It happens.

There are many stages throughout the life of a codebase. Whether you're starting from scratch, extending a bootstrap, or piling on a mountain of legacy Frankenstein code that you're worried about updating, how do you navigate the waters of shared code?

10: Find the Entry File

Your journey begins here! Thar be dragons. 🐲

Every program has an entry point. Most front end projects use an index.js file. Other programming languages use a similar file that represents the beginning of when the program runs.

Closely examining this will help you understand the flow of what you're reading. Here you may find functionality like:

  • Bootstrapping initial data
  • Setting up authentication
  • Making connections between shared systems
  • Landing or "home" page of a website

When loading up a project for the first time, it may not be obvious where to look to understand what's happening. Find the entry file and see where it leads you.

9 Help!

Mostly all codebases have some form of a helper file. Whether they are imported from a library or added by contributors, helper files do help.

Your mission is to see if there are any custom helper files. Custom reusable code added by contributors is an indication that whatever it's doing, it's essential enough to be shared.

Helper files usually have a variety of exported functions used by the rest of the application. Having them defined in generic files makes reusing in multiple places a breeze. Search the project for uses of any functions you find interesting. Please note how things are named, as they can provide clues to what they are responsible for handling.

8 Routes

The odds of the codebase you're contributing to having routes are high. No matter what the stack, routes are everywhere. From API's to URL's, route files give you insight into what is going where.

If you're working on a front end project, keep an eye out for how routing works by exploring the site. Click around, see where things take you.

Routes often have dynamic portions of the URL. An example could be /account/${uuid}. Follow that variable! Put the story together.

Taking a birds-eye view of the entire application will help you put it all in perspective.

7 Consistently Constant

At some point in the code's life, other files will need access to the same value. Much like helper files, constant variables get shared throughout the app.

You may find that the variables are IN_ALL_CAPS to indicate that they're constants. Variables written this way is an old-school naming convention used to communicate to the reader that its value won't be changing.

Examples of what you'd find in these types of files are:

  • API URL's
  • time formatting structures
  • secret keys or configurations

6 RTFM

Read (or write!) the F***ing Manual. Starting a new project involves some preparation. Planning docs can help you understand the business goals of the project. It's often these details that developers lack that lead to delays and confusion.

These come in design docs, feature specifications, workflows, user stories, user personas, storyboards, and many more. If you're lucky, you'll get access to some of these, as not every team has the people to produce quality documentation that others can follow. However, if you do, they will give you a greater understanding of what you're building.

Developer manuals are a different beast. This engineering-based documentation is to guide you through the code. Examples include Wiki pages, onboarding guides, Architecture Decision Records (ADR's), proposals, incident reports, readmes, and more. These docs are a goldmine for newcomers.

Having the goals of the business and the engineering specifics will help you become a better contributor. If you find yourself with little or no docs, then it's your turn to write them.

During your onboarding process, take note of anything that's missing. If you are following some docs that are outdated or incorrect, fix them! The next person will thank you.

5 Comments

Two forms of comments are crucial to understanding what you're building: discussion and code.

Examples of discussion comments are Request For Comments (RFC) docs, pull requests, and issue tracking software. These crucial nuggets of offline wisdom can help you understand how the code got to where it is. Check old pull requests to see how your team interacts when reviewing code.

Code comments are in the code. The kinds of statements are for humans - the maintainers of the code. They give readers a personal awareness of what's going on, describing business decisions or processes that aren't obvious by reading the code.

4 Follow the Herd

In an ideal world, the codebase you're working on reads predictably. It would look like every line was written by the same person.

Naming conventions are consistent, folder structures are intuitive, and everything is boring. Boring is good. It means that when you're kneedeep debugging something, it'd be simple to find and fix it.

When adding files, methods, functions, variables, or anything new, check for what's already there. Codebases are like one giant community-sourced story, a shared consciousness that lives in the code, and our minds.

Everything you read and write should look similar. Following established patterns makes extending and adding new features easy to follow.

If you're ready to break the chain and introduce a new direction or migration in the code, start with an RFC and get everyone involved.

3 Copy and Paste is your Friend

When contributing to existing codebases, you may find yourself adding functionality to something that similarly exists. If tasked to create a new page, look at other pages and emulate them. It could be the case that someone before you solved a problem that you can build on.

Examples of good copy-pastes can be error handling, page structure, and associated feature files that use similar functionality. Some frameworks offer command-line tools that generate starter files for you. Tools like this can increase predictability and productivity when contributing.

Adding a new feature could include creating similarly named files. For example:

  • account.js
  • account.test.js
  • account.helpers.js

Copy-pasting is only a start and should act as a template.

2 Tests

You may find yourself in a codebase without tests. If this is the case, you can be the one to write them.

Codebases with tests offer incredible insight into how a feature works. More importantly, they provide you a look inside your team's psyche.

Do they care about testing and quality assurance? Are the developers mature enough in their careers to see the value of testing?

Maybe tests aren't for every codebase. You may find yourself with the freedom of prototyping something quick, where tests may only slow you down. That's cool too.

However, if you find some tests, especially in production code that people depend on, run them yourself to see what's going on. If you've never written a test yourself, emulating what others have done is a great start.

1 Raise Your Hand

Don't be afraid to ask questions. Also, don't ask too many. You want to establish yourself as an independent thinker capable of figuring things out on your own. So, when do you reach out?

After you've exhausted every possible solution you could think of, maybe it's time. Before that, ask yourself some of the following questions as it relates to your work:

  • Is what I'm doing new for this codebase?
    • Odds are, some functionality exists which you can build upon for your feature. Check for similar functionality that may lead you to your answer.
  • Do I fully understand what I'm writing?
    • Too many times, software engineers code away without really understanding their deliverables. Get a clear picture of the result before working towards it. Googling all the things can only go so far without the right context.
  • Who can I ask for help?
    • Everyone is busy. While onboarding, it's helpful to have a point person to reach out to for questions. If this person doesn't exist, take the initiative for the next person.

Spread the Love

Everyone is new to something at some point. Someday you'll be asked to buddy up with new engineers. They may be veterans to the field or starting their first job with your team.

Help them be great.

If you see a mistake in onboarding docs, fix it. If there are none, write them yourself.

Is logic in some code you found confusing to follow? Add some comments to help the next person.

The code you write today will be maintained by you or someone else way after you've moved on. Make it count.

What would you recommend to someone contributing to a new codebase?

Top comments (0)