Right out of the gate, I felt it extremely important to talk through how I approached understanding the giant codebase of the first company I worked for as a software engineer. Just for context’s sake, the company is a large supply chain IT consulting firm that provides various services across the global supply chain network and works on various products that allow companies to optimize their supply chains in various ways, such as their e-commerce presence, order management systems, inventory management systems, etc. Without boring you with a lot of technical detail that I'm probably not legally allowed to divulge, the team I was on creates and maintains different API's and has multiple services running through them, along with different payment and e-commerce platforms we interface with, so there's a lot going on.

Needless to say, my first few days were ROUGH. I was confronted with a giant codebase that didn't make any sense to me whatsoever, from the size to the complexity, everything was intimidating. Once I decided to break down how I wanted to understand what was going on, things started to come together pretty clearly without even getting too deep into the code at the start. I’d like to kick things off by describing in detail how I approached the all too familiar problem of a giant and complex codebase during your first few weeks at work. Let’s dig in!

UNDERSTAND THE STACK/TECH AT A HIGH LEVEL

Hopefully, some of this information became apparent while you applied for any positions, or maybe you have no idea what the technology stack is at all, and you’re just aware of the languages used, either way is totally fine because this is the number one thing you should be trying to figure out. Knowing what technology we relied on helped me understand how our system worked at a high level. I was able to piece together the puzzle of our architecture during and after work with a few focused web searches about what each piece contributed to a system in general. The amount of time I was able to save understanding the tech stack upfront was enormous, and once I peeled back the layers and ventured closer to the actual code, I could refer back to which piece(s) were used within each file pretty easily.

A general understanding early on of the tech stack you’ll work in every day is so important to building a strong foundation as a software engineer. You’ll feel better about tackling bigger issues faster, and it does a great job of combating impostor syndrome that will surely come knocking every now and then (I will go in-depth on impostor syndrome in a later topic, don’t worry!). A great secondary effect of understanding the tech stack at work early on is that it will open your eyes up to the bigger world of system design, which if you’re not fully aware of what it is, is just the process of creating and connecting the elements of a system in a functional way. Regardless of if you choose to look into system design at a later date, the priority here is to focus on the work that you are doing now. Familiarizing yourself with your team’s tech stack as early as you can will pay off in a big, big way!

UNDERSTAND CRITICAL DATA FLOWS

Data is the lifeblood of an application, it comes in many forms, but I’m not here to discuss the technical aspects of how data moves in an application. What I’d like to focus on is the need and benefits of understanding how it moves through the application or system you’ll be working on. I like to think of an application as a giant factory that works on data in various ways, the logic used inside of the application transforms and directs the data to different places in the factory to needed areas. Knowing these flows can give you a familiarity with the system in a way that allows you to work on existing functionality and new functionality just as easily.

Imagine being able to quickly hop onto a new feature earlier in your career because you did the up-front work to REALLY understand how data moves and transforms. As a personal anecdote, there are a few database and caching services we used to optimize the way that we move, store, and transform data, and understanding how they all work is one of the most important things when trying to understand a new system. Getting a high-level view of where things like logging information went and where consistently requested data was being cached was SUPER important in building my knowledge. What would have taken me weeks to understand on my own was reduced considerably by allowing myself to be teachable in these early moments of my time with the team. 

UNDERSTAND THE 3RD PARTY APIs USED

API’s are everywhere, and they’ve become an umbrella term to describe some of the smallest single byte-sized tools to the largest multi-gigabyte systems. When you first come into contact with an application, you might see some of them and wonder what their purpose is and how it affects your data from the outside; at that point, it’s almost always a good time to explore and see what lies underneath those external API calls. API’s include systems like database interfacing programs like we discussed above, but in this section, what I’m referring to are systems like Stripe or PayPal for payments, Okta or AuthO for authentication and authorization, and many other platforms and tools that help with a critical function of an application.

The focus here should be understanding how they hook into your application specifically. Great questions that you should ask and try to answer are: What endpoints of their interface are we using? What’s the goal of each endpoint? What errors should I expect, and how are they handled? What kind of documentation is there for reference? How do we handle changes when implementation of the endpoints change on the vendor side? 

I’m a big fan of digging into each integration not only to figure out how we’re using existing endpoints, but predicting how we might use other endpoints in the future. As a new engineer on the team, you might not have as much decision-making authority right now, but hopefully, you will in the future, and staying up-to-date on the role these API’s play in your system can put you in a great position to lead or take part in new feature creation.

EXPLORE USER INTERACTIONS AND APPLICATION ENDPOINTS

This is an INCREDIBLY important thing to do that seems obvious, but to a new engineer, I'm sure the sheer size of a codebase can seem overwhelming, and it might not immediately come to mind to just play around with the application itself first. Keeping an eye on the network tab within your browser’s inspector tools and filtering to only see the XHR requests and JavaScript files ran was really helpful in my understanding of which endpoints were being hit and when. Observing the body and parameters of responses and requests was key to building my knowledge base of the web application I worked on. Once I hit an endpoint, I could reference it within the codebase of the API itself and follow the path to potential middleware that was used in validation or database interaction.

More generally, if you’re working with a system in general and not necessarily with a web application, always put yourself in the user’s shoes. Think about the utilization flow for each feature, write down questions that pop into your head as to why something works one way instead of another. Do you have any assumptions about how a piece of the system works, and then you find out it works completely differently? Working through these thoughts helps build a knowledge base of the features you’ll come to know and love when working on them, allowing you to more confidently tackle problems and ask more pointed and focused questions when you need help.

PULL DOWN THE CODE AND EXPLORE

This is the point where I really decided that I had done enough of the upfront work to feel sufficiently confident to dive in and explore the codebase fully. I tried to do this in a way not to overextend myself while peeling back the final layers of the application. While reading my approach, please keep in mind that while browsing the files, I made sure to lean on prior information gathered from the above steps, everything done up to this point was to really make the source code exploration process easier.

The first thing I made sure to do was pull down the code in a location that was accessible and clear. There’s nothing more annoying than having your team’s code repositories all over the place, put it in a folder that makes sense and either on your desktop or somewhere you frequent and keep it there, simple!

The second thing I did was read any internal documentation about how the files connect to and depend on one another, as well as how they work independently. Being aware of dependencies is another glue that helps bring together the application conceptually, you’ll be able to really understand how data flows not only from a database perspective but how it's utilized and which pieces of the application uses what data. A strong footing can be gained just by understanding internal application dependencies alone.

The third and last thing I focused on was how I should go about understanding each folder/directory and in what general order. You wouldn’t go on a trip somewhere without prior knowledge about places to eat, hikes to go on, or museums to visit, right? The same principle applies here when exploring a codebase; making sure to ask more experienced engineers that know the lay of the land is much better than exploring without any idea of how to navigate it.

UNDERSTAND QUALITY ASSURANCE/DEVELOPER ENVIRONMENT

Underneath complexity lies many simple concepts that underpin it and work together in unison. Going through the setup of the development environment with a more senior engineer can help you really understand what's going on in the application at a deeper level. I imagine setting up and understanding development and testing environments as the scaffolding that allows the tech stack to be experimented on as you understand how things work at a more technical level; this is peeling the figurative onion back another layer. 

Throughout setting up, try to focus on why certain tools are being installed, ask questions such as: Are the tools for testing or running the application? Are they required before or after certain steps to run the environment properly? Which tools are meant to be used before, during, and after running the application? These and a lot of other questions that I’m sure you’ll think of are incredibly helpful in gaining a solid footing as a new engineer on the team.

As you finish setting up your environment, try to step back and look at it from a higher level too, try and visually map out how the pieces all connect, and what happens if you didn’t have one of them or something went wrong. A cool exercise I like to do is search up alternative for those tools, for instance, Grunt was used as a task manager for a lot of our systems written in JavaScript, but there are a lot of other task managers within the ecosystem, and learning a bit about how the others work can help aid in how you understand the similar tools you’ll use daily.

CONSIDER ANY “CLEANUP KNOWLEDGE”

I kind’ve consider this the “cleanup” phase of anything you feel like you might have missed while gaining a general and technical understanding of the application at multiple levels. Oftentimes while we’re consuming so much information, we can miss some of it while peeling the layers back, and that’s totally okay. I try my best to create a cleanup folder of text files, PDFs, documentation links, and any other resources that I can read up on later. What matters most for the first six steps I laid out is that you have a solid understanding to put you in a great position to succeed. Missing details here or there is okay, and will be revealed soon enough as you continue learning on the job, remember no one knows everything right off the bat, and everyone makes mistakes, just do your best and strive for excellence!

CONCLUSION

I continue to use these techniques in and out of work. They’ve allowed me to push myself and understand how and why things work instead of blindly hacking away at a problem. It enables me to help others in a big way whenever I can, and I appreciate the discussions I can have from learning about a new tool or set of tools with someone learning the same things or a concept that the tool depends on. I hope you’ll come to appreciate the approaches here and how I’ve applied them!

CHAPTER REVIEW

1. Get a solid understanding of the tech stack.

2. Ask more experienced engineers how critical data flows and transforms throughout the app.

3. Make an effort to understand any critical 3rd party API’s used within the system.

4. Explore user interactions (if there is a front end to interact with) and observe behavior from the perspective of the user.

5. Pull the code down and explore the codebase while referencing any relevant internal documentation on the codebase itself to help orient you.

6. Gain an understanding of how the development and any other testing/staging environments work, as well as how to troubleshoot potential big issues.

7. Consider any extraneous knowledge needed that helps with a deeper understanding; this should be knowledge that’s useful but not needed to work within the codebase.