Reading code, just like writing it, is an important software development skill that takes lots of practice. When joining an existing project, you can’t start contributing until you’ve oriented yourself within the codebase. Developers also rely on these skills to learn from other projects and collaborate with others on code reviews.
But while there’s a variety of websites dedicated to helping developers practice programming, there aren’t a lot of resources focused on helping developers strengthen their reading abilities. So those who are looking to get better at reading code — and on improving their software development skills in general — should find opportunities to practice on their own.
5 Tips for Practicing Code-Reading Skills
- Pick the right codebase. Learning about new industries, languages and frameworks is great — but don’t try doing all three at once.
- Use tutorials and documentation. They will help keep you from getting lost.
- Scan the codebase to get a sense for the big picture.
- Run the program to see how it works, if you can. And if you download the code, you can try breaking it.
- Set a timebox. Or embrace the journey.
M. Scott Ford, co-founder of legacy code software consultancy Corgibytes, is a pretty good code reader. It’s a skill he developed over time — ever since high school, he’s spent countless hours poking around in codebases. He’s even curated a list of GitHub repositories he recommends for code-reading practice.
Scott said developers can learn something from almost any program they have access to — something that’s much easier now with the popularity of open-source projects.
“What makes them good is that they’re available,” he said.
Why Reading Code Is An Important Skill
Despite the stereotype, developers don’t spend all of their time pounding the keyboard and cranking out code. Most developers work on teams, where the codebase is usually much larger than what one developer can produce and manage on their own. Being able to navigate around a codebase, regardless of whether the code is familiar, is one of the most important and useful skills a developer can have.
Reading code isn’t like reading a book cover to cover. Sometimes developers need to drill down and understand the technical details of a section of code, but it’s just as important to know how to skim. Skimming is useful for tasks like debugging, which requires hopscotching through a codebase to track down the cause of errors. If a developer has trouble navigating unfamiliar code, they could waste a lot of time trying to orient themselves.
Developers who work on teams also need to give good code reviews, which are essential to maintaining code quality and security. But giving good code reviews is hard if developers have trouble understanding unfamiliar code. And developers also read a lot of code from outside their own organization, like online tutorials for learning new technologies and open forums when they need help while troubleshooting.
The good news is that reading code is a learnable skill. Here’s what you should keep in mind if you want to pick it up.
Practice With the Right Type of Codebase
Some codebases may be easier to learn from than others, at least at first.
Scott said it’s best to choose projects where you’re not new to too many things at once. For instance, if you’ve only ever written in Python, diving straight into C# code written using a .NET framework in an unfamiliar industry may not be an efficient way of learning.
“Look at something new, where maybe only one thing is different from your current experience,” Ford said, giving the example of a project where the programming language and the operating system are familiar, but that uses a different framework. “By looking at this codebase that’s written in this other framework, I can start to gain an appreciation for what’s different between the framework that I know and the framework that they are using, and maybe gain some insight into how that framework works.”
With that said, reading code that’s written in an unfamiliar language and framework could help give a general idea of how things are done in a different paradigm.
Take Advantage of Tutorials and Documentation
Just as tutorials are used for writing code, they can also help developers practice reading code by laying out the structure of programs upfront. Ford said developers reading code written in an unfamiliar framework can even use tutorials for that framework as a guide.
“The tutorial would say, ‘For a new app, you would have to create X, Y and Z for these reasons.’ So you can go look for those things in the app that you’re reading, to try to get a sense of what file that might be in,” he said. “If you’re just reading through, it can be extremely easy to get lost without some kind of guide to look at.”
Other types of documentation can be useful as well. The developer of the original Prince of Persia game published the journal he kept while creating the game in the 1980s, which Ford found useful to compare against the game’s source code.
“You can look through the journal and also look through the source code, and just see a little bit of the challenges that had to be tackled and how different things were kept track of,” he said.
Having someone good at reading code available as a sounding board can be even better than tutorials and documentation. They can give feedback, and simply watching them read and navigate code can give less-experienced developers ideas for different ways to approach it.
“If you do have someone you can ask questions of, a great way to learn is to ask them, or maybe even watch them, do it side by side with them,” Ford said.
Scanning Through Code Can Offer Insights
It might be tempting to hunker down and read through a codebase line by line, but Ford said a surprising amount can be learned just from skimming through a project’s source code. It’s a good way to see how different developers handle things like naming conventions and writing comments.
“It might be teaching you things that you don’t even realize you’re learning along the way,” Ford said. “Like, how should files in a large project be organized? What kind of documentation do newcomers need?”
Developers can scan through codebases quickly if they hop around files and don’t get bogged down in the details, allowing for more exposure to a wider variety of code. Developers can also let their interests guide their reading, such as looking for how other developers structure data or interface with services.
For instance, looking at codebases can teach developers about how code safety is handled at other organizations. Ford pointed out lines of code in Microsoft’s calculator codebase that showed how the company’s developers handled error checking and suggested questions to consider while reading through code other developers wrote.
“Do they just assume that when they call something, they get a value back and that’s a valid value?” Ford said. “Or do they check some assumptions that they have as a consumer of that value to make sure it’s correct?”
He suggested turning reading code into a scavenger hunt — for example, searching for the section of code that performs a certain operation, like the addition operation in Microsoft’s calculator code. A good method is to do a search for specific keywords in the program.
The Best Way to Learn Is Running the Program
Developers can interact with the codebase if they download source code and run the program locally. Breakpoints can be set in the code before running, which pauses the program at different points of execution and gives sneak peeks into its state.
“That’s always really powerful for figuring out what’s going on and why,” Ford said. “If that’s your motivation, you’re best off downloading it and getting it to run inside of a developer environment. Then you can actually watch the computer executing the program line by line. You can gain an understanding for what each line is doing and why.”
Developers can also make modifications to the code, such as writing values to the console during execution, another way of tracking changes in the program’s state. And because all changes are local, there’s no need to worry about “messing up” the code — developers can play around by making the program behave in new ways and even by trying to break the code.
Unfortunately, running the code locally doesn’t work for all programs. The code for the original Prince of Persia game is written in assembly language and developed for the Apple II computer, which makes trying to run that code much harder.
Set a Timebox, or Embrace the Journey
Unfamiliar code and frameworks are confusing. It’s easy to get lost down rabbit holes or trace a thread of execution, only to realize you’ve gotten nowhere hours later.
For situations where you’re looking for a specific answer, Ford recommended setting a timebox before starting and moving on to a different resource if you’re not able to find the answers within that time.
But getting lost in the code is not necessarily a bad thing.
“You can also learn a lot by stumbling in the dark,” Ford said. “One of the most useful skills that I don’t think it’s talked about enough is dealing with frustration, dealing with not knowing how you’re going to get the answer to the question, but trusting enough that you’ll figure it out.”
When Ford was just starting out as a developer, he spent weeks hunting down a bug in the source code whose fix turned out to be just a few characters. He said every developer’s journey is unique due to factors like the knowledge they have, the code they’re looking at, their state of mind and how much time they have. Developers who practice reading code beyond their current understanding can help them get comfortable with being frustrated, and learn that it’s possible to come out the other side.
“Learning to be OK with that is part of that skill,” Ford said. “‘It’s OK that I’m lost, I’ll figure this out.’”