Some companies’ codebases are massive. FreeAgent’s, with its monolith Rails application, certainly is no exception. The first time you clone one of these codebases onto your machine and see the sheer number of folders, files and complexity, your eyes might just widen and your jaw may just drop – letting out a yelp. As you click through the first few random files, noticing that you don’t understand a thing and that it takes a while just to scroll through the folders in your file explorer, you’ll quickly realise why it is called engineering.
I have more bad news: the chances are that with each new project card, you’ll be tinkering with a separate, and again unfamiliar, section of the codebase. But fear not, for there are ways you can make this challenge easier and build your confidence in figuring out what the heck is going on.
A sea of syntax
When you sail out on your first task, it can be easy to get lost and overwhelmed by all of the syntax and code in the files you’ve opened. Attributes on a div that you’ve never seen before, long-named methods that don’t seem to be relevant, and the intimidating stimulus controllers may stick out like lethal icebergs. Thankfully, icebergs can be navigated around. A great thing about working with existing codebases is that oftentimes you don’t need to worry about a lot of the code at a low level; the majority of it you can safely ignore – it just works.
So don’t worry about reading a file through line by line and failing to understand past the fifth. Though there are icebergs, you come to realise the sea isn’t always rocky, and steering around them is not so difficult. What is more important is that you slowly but surely build a high level understanding of what sections of the codebase do.
Useful tools/techniques (for VS Code, though other IDEs may have similar features):
- Github Copilot Extension
Mac: Ctrl + Command + I (^⌘I)
Windows: Ctrl + Alt + I
Tip: Adding a file to Copilot’s context and asking it to explain to you what it does is a really effective way to get a quick, high level summary of what it does without having to dig through the code.
Swim around
The best and most crucial advice I can give is this: set aside some extra time, whether it be 15 minutes or an hour, to just explore the code around your task without trying to complete it. You could click through definitions of methods, change some text in a view to see how it reflects on the webpage, add in some print debugging statements to see when, and in what order, things are triggered… get creative with it!
Even subconsciously, you’ll start to pick up on patterns of code structure, how methods are named, what files and sections are coupled, the general path formats for different components, and more. This is invaluable to get an insight into “how things work around here”, where “around here” can be as large or small a chunk of the codebase as the context requires. This makes the actual attempt at your task much more digestible – you’ll likely have already started to discern ways you could implement it as you swam around.
Useful tools/techniques:
- Search tab
Mac: Shift + Command + F (⇧⌘F)
Windows: Shift + Ctrl + F
Tip: If you know where in the app you need to work, but are unsure of which file, copy some text from that page and search for it in the codebase. This should help you find the corresponding file and is a good starting point to swim around from.
- Go to definition
Mac: Command + Click (⌘ Click)
Windows: Ctrl + Click
Tip: This is very useful to find coupled files that are relevant to your task as it takes you to the method definition, wherever it may be in the codebase. You can also use it to get a deeper understanding of what is being executed, and how.
Dive deep
Now you’ve mapped out the surroundings, it’s time to get into the specifics and take on the task. Hopefully you now have an idea of where to begin, and to pinpoint it you can make use of some of the techniques mentioned before.
Then get writing code! Studying the codebase beforehand should give you the confidence during implementation that you aren’t breaking anything and are writing code that fits in with the standards. It also helps to prevent extra, unneeded work. Before familiarising myself, I’ve spent hours defining new methods just for an engineer on my team to tell me during a review that they already exist somewhere, and then I’ve had to spend more time refactoring my solution to use them.
To boil it down, you’re trying to find out what there is, what you need, and how to use it. Before you know it you’ll be picking up project cards with conviction – without being stressed it may be a bit beyond your pay grade despite having assigned your name to it – as you can accurately scope out where and how changes may have to be carried out in advance, gauging the size and complexity of them.
Useful tools/techniques:
- Reference similar features
Tip: If you notice that something similar to what you are implementing already exists somewhere else in your company’s software, find it in the codebase and have it open as a reference to see how it’s done.
- Quick Open (file list)
Mac: Command + P (⌘P)
Windows: Ctrl + P
Tip: This allows you to search for files in the codebase by name, so it can be useful to find code related to a feature by searching for its name. It also saves a lot of time as opposed to digging through folders in the file explorer.
Back aboard
Like any skill, learning how to get to know a codebase requires dedicated time and practice, so adopting these tools and tips into your arsenal early is sure to help get you to grips with your company’s codebase. Good luck on your voyages!