Congratulations! It's your first day at your brand, spankin' new developer job! You've signed all the paperwork, set up your desk and have already pillaged the free snacks. You're feeling all sorts of happy... until you spin up the codebase and you see what you will be "working on" for the foreseeable future.
Directories. Sub-directories. READMEs. Testing Suites. And files.... hundreds and hundreds of files! The panic is REAL.
But don't fret. This phenomenon happens to EVERY developer - from the seasoned Senior Engineer all the way to the newer Junior Developer. Regardless of where you fall in your career trajectory, this post will help give you some strategies to diving into a new codebase so you can ramp up quicker, feel less stressed and start writing great code!
Cut Scope
Look, there is no way that you will be able to understand how every single piece of the codebase is working until you've been working in that codebase for quite some time.
So, rather than wrack your brain about how you will come to understand it all, take a deep breath and cut scope.
A good question to ask yourself is "What part of the application do I need to understand FIRST?" There is no exact science to figuring this out, but it can be a good first step into diving into the codebase and the application itself. While there are many entry points into the codebase, picking one and going from there will help make things less overwhelming!
To The Tests
OK, so you've decided on a part of the app that you want to focus on. But even that pathway still presents an overwhelming number of potential files and dataflows to parse through. Rather than absently click through every single "potential" file, it is better to run the tests associated with the pathway you chose.
Besides ensuring that the code is stable and ready for production, the tests should hopefully provide some documentation on how the code is working and what it does! This approach can give you some insight into commonly used conventions in the codebase, how functions are being used/reused, etc.
But as we all know, there will be times when test coverage is lacking or non-existent. So, where do we go from here?
Experiment with the App
Rather than just look at file after file, a good way to start understanding the app is to actually engage with it! All software has an end user - going through a portion of the application from that users perspective will give you valuable insight into, including...
- How the app works
- What the user experience involves
- Potential pain points a user would experience
To really enhance your understanding through this process, it is important to utilize any relevant development tools as you work through the application. For example, if your application uses a framework such as React, you can utilize the React Dev Tools to determine component structure, what data is being passed through as props, etc. as you interact with the app.
Additionally, feel free to experiment with the code itself and seeing what impact it has on the experience! Strategies such as using debuggers, commenting out code, or adding small snippets of your own code will allow you to see how certain parts of the app are working as you go through the user flow!
Follow The Data
Production-level codebases incorporate a frontend and backend codebase that communicate together to send, create, update, and display data. It is crucial to understand how these two systems communicate together to truly understand a codebase. Luckily, there are a lot of ways you can begin to do this!
For example, many applications follow a MVC architecture pattern - whereby there will be a model, view and controller - each responsible for handling certain functionality within the app. You can analyze the file structure within your text editor/integrated development environment (IDE) to get a sense of where these respective files are stored and how they are organized. You can then "follow" the flow of data from models to controllers to views. This scavenger hunt works even better when you are able to utilize your developer tools as mentioned in the above step to see if any of the data/function calls can lead you to explore other related files.
Use Your Tools
As you start to move more into the code itself, it is important to leverage the tools baked into your text editor/IDE that make it easier to scan and search within a large project or codebase.
Let's say you've identified a file that is related to the functionality you are currently exploring. You can search for any imported methods, data, etc. using the search functionality within your editor. Often these are set up to search within the file you have open, or throughout the project as a whole.
This process of analyzing a file and finding functionality coming from another file can start to help you piece together how different parts of the app communicate with one another!
Take Notes
As you start to dive deeper and deeper into the codebase, it can be extremely helpful to document what you've learned so far and keep tabs on what you've already explored.
Code annotations can be a great way for you to leave yourself notes about how certain functionality works, how certain files connect, or even ideas you had as you worked through the app from the perspective as a user! I personally like to use code comments to jot down my thoughts and notes, typically working on a separate branch where I can add these without worrying about confusing other developers on my team.
Also, as you begin to see how different parts of the application work together, it can be extremely useful to diagram how data flows from one part of the app to another. There are plenty of tools that you can use for this - from good ol' pencil and paper to digital tools such as Figma or Miro.
You may also want to consider creating an Entity Relation Diagram (ERD). These can be used to to visulaize database tables and their relationships. This tool can be really useful for understanding the data you are working with within an app. One tool that I've found useful is DB Diagram.
Share Your Knowledge
As you take steps to dive into a codebase and learn about its inner workings, it is always a good idea to share what you've learned to your larger team! There may be other new developers on your team who could benefit from your research and diagrams. Also, you may have some more senior engineers on your team that can provide valuable feedback on your notes, diagrams and understandings. Remember, while it may take a bit of time for you ramp-up to the point where you can enhance the codebase, this early research can be incredibly valuable for the entire team.
Final Thoughts
Learning the intricacies of an unfamiliar codebase is a very difficult and time-consuming endeavor. There will inevitably moments where you get lost in the code, misunderstand how data flows in the app, or encounter code that you don't understand at all. Rather than get frustrated or upset, recognize that this is all part of the process for truly learning something new!
While this process will always be a little prickly and tedious, utilizing some of the strategies above should help you to refine your process for breaking down a large codebase. If you have other strategies that have worked well in the past, please add them in the comments below!
Don't have that first job yet but still want to get your feet wet with this process? Luckily, the Forem platform (which powers DEV) is completely open-source and provides a good sandbox for you to start putting these strategies into practice!
Top comments (1)
Great post! I find 'scope' one of the trickiest things. The desire to get a high-level overview of how everything fits together is really strong, though it's usually a fruitless endeavor. Far better to focus on very specific parts of the application.
Incase its useful and you don't mind me sharing something we made for this: we built an ERD tool specifically for exploring and getting your head around existing databases (rather than designing new ones): trevor.io/create-an-er-diagram-onl...