Parachuting Into a New Codebase

As developers, we will frequently find ourselves working with codebases we didn't create. At first glance, these systems may have complex file organizations, convoluted function interactions, foreign code structures, and mysterious symbols. Building the skill of understanding code and systems that you did not write or design is crucial and time-saving. This guide offers practical strategies to help you efficiently navigate and comprehend unfamiliar code.

Why Improve your ability to navigate unfamiliar code bases?

• Understanding system architecture and file organization is essential but time-intensive.
• Finding the right files to modify can be frustrating and experimental.
• Effective navigation techniques can dramatically reduce onboarding and development time.

Steps to Find your Bearings

Step 1: Initial Reconnaissance

1. Get oriented with the file organization

Look over the files and folders just to figure out what’s there and what’s where. Check if there’s frontend code, backend code, or both. How are screens and pages organized? Are images kept in a separate folder? Where are the CSS files? Are helper functions abstracted out? Identify what languages are used and what they do—this is important so you know how to print. This helps you build intuition about where different parts of the project are located and where you might find what you're looking for.

2. Figure out how to run the project

• Check the README.md file for run instructions. This file would usually contain detailed instructions on how to set up and run a project, including information like required dependencies, installation steps, commands to execute the project, and any specific environment configurations needed to run the code properly, etc.
  

• If the run instructions are not in the README file, look into configuration files (e.g., package.json, docker-compose.yml) for clues. These files specify dependencies, scripts, services, and environment configurations needed to set up and run the project and have a section that outlines how to run the project locally.

For example:

In package.json, check the run instructions. Under the script section,  you will find a list of terminal commands that may run, build, deploy and etc. your project.	Identify which package manager the project uses. The most common are npm (package-lock.json file exists) and yarn (yarn.lock file exists). Then use the correct packet manager command to execute the command. eg. To start a project, use either yarn start or npm start, depending on the package manager used.	Check the console for errors. These usually contain further clues or corrections that help you correct run the project

Step 2: Poke and Observe

At this point, you likely have a task or goal in mind—whether fixing a bug or adding a new feature—and need to find the relevant files to edit. Now that you're familiar with the file organization and have managed to run the code, we’ll take a Dr. House approach to locating the correct files and functions: change something and see what happens.

Helpful Tips:

• Modify UI Elements: Try changing colors, font sizes, or text content in the UI to confirm you're in the right place.
• Print Debug Statements: Use console.log(), print(), or equivalent statements to check if a function is executing and inspect variable values.
• Comment Out Sections: Temporarily disable parts of the code to see what breaks or changes, helping you pinpoint dependencies.

Navigation Tools:

• Browser Inspection: For web development, most browsers come with built-in inspectors that allow you to view the HTML governing the page content. This is useful for examining HTML elements, their hierarchy, their classes, and other debugging and tracing tools.

Inspect Element	Evaluate HTML
Chrome: Right-click > Inspect Safari: Right-click > Inspect Element	You can identify what each HTML tag is responsible for rendering, helping you locate the section you need.

• Print as you go: Print statements help with: -Check if a function is running. -Check the control flow. -Provides an X-ray into variables and parameters; it can print entire file structures and almost any data type.

  
  When printing there are three main places your output might appear:

Terminal Console	Browser Console	Log File
This is usually the terminal that you used to original run your project	Chrome: Right-click > Inspect > select the Console tab Safari: Right-click > Inspect Element > select the Console tab	the log file is a computer generate file that logs user actions, error messages and print statements (depending on the project settings)

• Use IDE code navigation features: Visual Studio has a host of "Go To" features that allow you to quickly locate definitions, references, and implementations. Simply, right click on any function, variable, element, object etc.

• Guess the file, function, and variable names using common words and syntaxes: It's good practice to give variables, functions, files, and other structures intuitive names that follow standard conventions. The benefit of this is guessability—if you’re struggling to find something, you can often predict its name. This makes searching easier using the search (Shift + Cmd + F) feature to search the entire project or find Cmd + F feature to search within the current file.
  Eg. if you're looking for a function that formats dates, you might try searching for keywords like "formatDate" or "parseDate" to quickly locate it.

Summary

Quickly understanding a new codebase is essential. This guide covers key strategies like file navigation, browser inspection, print debugging, and IDE search tools to help you locate and modify code efficiently.