While there are a lot of articles and classes about designing and creating good code, tutorials on how to effectively read code are few and far between. This is an important skill because one of the fastest ways to level up on your own technique is to learn by example. But even if you don’t want to curl up to a nice application before bed, understanding how other people’s code works will be integral to your daily life as a programmer.
Opening up a new repo and trying to figure out how the magic is happening can be daunting, but there are strategies to finding your footing. I’ll try to break down the strategies I’ve learned to help you start on the path to becoming a codeworm and digging into code you haven’t seen before.
Step One: Don’t Read the Code
Before you start reading the code, figure out what you can lean on that’s not code to get an understanding of what’s going on. There are a number of tools you can rely on to get an idea of what’s going on in a code base without having to throw yourself in the trenches.
Comments: Skimming through the comments might prove helpful to understand specific functions, but be aware they can sometimes be out of date.
Specs and Documentation: A lot of people automatically seek out the documentation for a project, but forget there is a lot to grok from the specs as well. Utilizing these two resources should help you get a high level overview of the intentions of the feature.
Tests: When in doubt, look up the tests for a section of code. They should have descriptions that map out the intended effects of each function.
Developers: If all else fails, figure out who else has touched the code and reach out to them to explain the higher level concepts. There are two git commands you should be familiar with here: git blame and git log. I’ll teach you some flags to optimize your usage of these tools.
git blame [filename]
git blame -L 356, 357 [filename]
git blame -w [filename]
git blame -M [filename]
git blame -C[filename]Git blame [filename] prints a list of the ID, author, timestamp, line number, and line content of each change in any particular file.
- -L [number], [number] will restrict the output to a specific range of lines in the file.
- -w will ignore whitespace changes, which may obscure meaningful changes to a file.
- -M will show you lines that have been moved or copied within the file you are searching and the author of the original content.
- -C finds lines that were moved or copied from other files and will report who created those lines instead of the person who moved or copied them.
git log
git log --oneline
git log --after="2019-3-6" --before="1 week ago"
git log --grep="[search-term]"
git log -S"[search-term]"Git log will print a history of commits for the overall repository.
- — oneline: using the flag condenses the print message to the commit ID and the first line of the commit message. This can make it easier to scan through commits and get a picture of major changes to the project.
- — after=”2019–3–6" OR — before=”1 week ago”: filters the commits found by date. You can use specific dates or relative dates like “1 week ago” or “yesterday.” The commit history is inclusive, so the changes made on the date you list will be added to your list.
- — grep=”[searchterm]”: finds all of the log messages that contain the search term.
- -S”[searchterm]”: finds all of the commit messages of commits that contain the search term.
Step Two: Mess With The Code
Reading code should be an active experience. You have to engage with the application.
Make a goal for what you want to understand and don’t get lost trying to understand functions that aren’t essential to your goal. When I was in school we watched a documentary from 1968 called Cosmic Zoom that zoomed out into the cosmos and discussed space before zooming in and talking about microcosms. You can find these extremes in understanding as you’re looking through code. You don’t need to understand how every number is determined, but if it is essential to what you want to change, you want to be able to zoom in enough to understand how those numbers are derived.
Your first step should be to find main, or the entry point of the code. Ideally, you should be able to run the code, and use breakpoints in a debugger to follow along the steps. If so, you can find the call stack and figure out how your program is unraveling. If this is not an option, printing out statements in different functions should help you get an idea of the order of operations.
You’re goal is to break things down as you’re following the trail of logic. A lot of times the “meat” of a file is near the bottom, with smaller functions that are used in those final methods at the top so it can be helpful to read files from the bottom up to get a higher level overview of what’s going on before you dig into the details.
Stay active as you read. Rework files to figure out their flow. Changing variables you don’t understand can help you get an idea of how they are being used. One study found that physically writing out the changes in a variable instead of trying to rely solely on memory to track changes in code was immensely helpful to students as they tried to understand alterations to code. Another hands-on strategy to understanding code is to try to refactor it into smaller functions. Can you replicate the effects?
As you read through the code, pay attention to the names of functions and files and try to create a flowchart of what’s going on. Understanding code is just understanding how a lot of different moving parts interact together, so figure out which parts are important to your mission and how they are composed.
I started this article saying I was going to teach you to be a codeworm and comparing the logistics of understanding an application to reading books. However, hopefully by this point you’ve started to understand that “reading” code is a lot more about unraveling a trail of logic and actively using tools to manipulate data to help solidify your own understanding rather than passively glancing through which functions are named what.
This might require more effort, but as you can see, there are definite strategies you can employ to get the most out of the effort you are expending. If you are looking for what to learn next, I recommend looking into keyboard shortcuts and methodologies to grep functions and navigate through the text editor you use.
Hopefully the strategies I’ve listed today will help as you continue honing your skills by learning from others and getting better at finding your way in the dark through the practice of reading code.
📝 Read this story later in Journal.
👩💻 Wake up every Sunday morning to the week’s most noteworthy stories in Tech waiting in your inbox. Read the Noteworthy in Tech newsletter.
