There comes a time in every developer's life when they start a new job, join a development team or decide to contribute to an open source project and you’re faced with a new, large, unfamiliar codebase and a bug to fix. The codebase is something of a size you’ve never really seen before but don't worry, I am going to share a few tips and tools for how you can make sense of other people's code without going crazy.
You Don't Necessarily Need to Know Everything 🤯
It was a game changer for me to realize that I simply can’t understand everything. Lots of beginner engineers are ambitious and want to read everything. The spirit is good; however, no, you simply can’t, period. It is important to prioritize what code you want to understand, and what code to skip.
Read the Docs 📖
The first place I start with a new project is reading over any available documentation or README files. This allows me to become familiar with the setup, functions, style, and other important parts of the codebase. Some parts of the documentation might be out of date, but seeing the evolution of code can also help to understand the project’s history. Unfortunately, sometimes, the documentation isn't complete and it may be wrong.
Use Command Line Search Tools 🔍
It is not always easy to be immediately effective when you dig for the first time into a codebase containing several thousand of lines. But my secret weapon to find my way through so many lines of code is command line search tools like
ack. Searching for a unique string or keyword is an excellent way to find out where a functionality is located without jumping into a text editor. I'll demonstrate how I use this handy method to immediately find out what file(s) I need to look at to fix a bug.
I've recently started contributing to the DEV source code and I highly recommend everyone to do so as well. It has quite a large codebase and the maintainers are extremely welcoming. I believe it is a perfect place for junior developers to contribute to the open source and put their knowledge into practice.
I identified a bug and reported the issue, and I wanted to try to fix the issue myself. Consider that DEV's backend is developed with
Rubyand I am not a Ruby developer but what I needed to fix was the HTML code that was returned to the browser. I had no idea what file I needed to look at or where the function was.
I opened up the dev tools and realized that the
<div>element in question has a class name of
ltag__twitter-tweet__video. Running the string through
grepI found three files I needed to look at:
$ grep -iRl "ltag__twitter-tweet__video" app/
Cool, right? The nice benefit of using
grep is that it’s available on pretty much any ‘nix distribution you might use. Its utility is powerful in many different contexts. To learn more about grep, make sure to check out this post.
Ack is “a tool like grep, optimized for programmers.” It searches recursively by default (i.e., your project) while ignoring VCS directories like .git and has convenient tools that help you explore code with fewer keystrokes.
Taking the same grep example, here’s how we would search for “ltag_twitter-tweet_video”:
$ ack "ltag__twitter-tweet__video" app/
9: <div class='ltag__twitter-tweet__video'>
30: el.getElementsByClassName("ltag__twitter-tweet__video") .style.display = "block";
Ack is my trusty search tool of choice and I think you will get a lot of value in using it as a grep replacement. I would highly recommend learning how to use ack. Consider reading this to learn more.
Finally, if you’re still stuck… then ask! A great way to gain knowledge of a project when starting out is to pair with a developer on your team who is more familiar with the codebase. This person can provide high-level insight about particular design patterns, testing, processes, and third-party code that are relevant to the project. They can also give you more historical context about the project and why certain choices were originally made.
And those are my tips! Hopefully this helps with the daunting task of unfamiliar code. Please try not to stress. Breath, remember these and you’ll be fine!
What ones do you have? I'd love to hear your tips and tricks as well.
I am a full stack web developer and co-founder of Bits n Bytes Dev Team, a small group of highly talented and professional freelance developers, where we provide custom web application development services based on cutting-edge technologies, tailored to client's unique business needs.