Learn How to Read Code
When thinking about natural languages, in school you received lessons on both reading and writing and were graded on your proficiency in both.
So, why doesn’t learning to read code get taught nearly as much as writing code? After all literacy is defined as a person’s ability to both read and write in a language for a reason.
If reading code is a skillset, what are signs you or your team lack it?
- Sign: code duplication
Scenario: Developer A writes a function. Developer B needs to use the function but can’t read it so they write a new function that does the same thing. - Sign: lack of documentation
Scenario: Developer C solves a tough coding problem. They piece together their code with code from multiple StackOverflow answers. They can’t read what all the code is doing and therefore they don’t write documentation for it. - Sign: code misuse
Scenario: Team A is using a package to handle some functionality. They don’t take full advantage of the api because the package, like many, only documents part of its api. And because they can’t read the source code they are missing out on features. - Sign: lack of feedback on pull requests
Scenario: Developer B makes a pull request for a new feature. Many files have been added, removed and modified. The PR only gets a few comments before it’s merged. Once QA looks at it (or worse yet, it makes it to production), many defects are reported.
As a quick exercise, reread those bullet points but replace “can’t read” with “doesn’t understand” and you’ll arrive at the heart of the problem.
Often times when a developer “can’t understand” another person’s code, the onus is on the code’s author to WRITE READABLE CODE. You hardly ever see someone being asked to become a stronger a reader.
This matters because most of the time when a developer is reading code, they don’t have control over what’s written. Being able to read code, even bad code, is a skillset. After all if you’re reading a lot of code because you’re doing a refactor, you wouldn’t be refactoring the code if it had been written at JK Rowling level of excellency, amirite?
Being able to read code is important. Now, how do you get get there?
Steps to Learning to Read Code
- Start with the easy stuff. Remember, no one gives Othello to a kindergartner. Instead they start with Green Eggs and Ham. Code is no different. To get better at reading it, start with code you’ve written yourself. The more recent the better. The shorter the better. For example purposes, I’ll use a real JavaScript function I’ve written for work.
2. Add comments. Once you’ve found your right piece of code, go through and add comments. Here are few ideas to get you started
- Notice that comments where added 1) above the function, to describe the code’s function at a high level. 2) above each conditional to explain in words the branching logic
- Adding comments to each piece of code, like the above is an exercise to help you learn how to read code better. Generally, you shouldn’t commit code that is commented this much.
- Normally, after reading code that you’ve written, you might have a few ideas on how to improve it. For example, with the above function, I noticed after doing this that
newPatientis a poor name for what the function is actually doing.sendToNewPatientRouteis a longer name but more descriptive, accurate and self documenting.
3. Notice imports and dependencies. In the example code, onConfirmClearClient() and clearActiveClient()are both functions declared in another file. When it comes to imports and dependencies, reading these functions can help you better understand the code at hand. However, beware of falling into a rabbit hole here as dependencies can have dependencies which can also have dependencies with dependencies.

4. Read other people’s code. This one is huge. If you have a job as a developer then look at code that your teammates have written. If you don’t yet have a dev job, you can look at other people’s code on github. If you go with the latter, do not try to read the entire repo. Instead start with a single function in a single file.
As you work through reading the code (adding your own comments), here are some questions to keep in mind:
- What does the code achieve at a high level? What is it responsible for?
- Does it take arguments? What are their types? Which are required and which are optional?
- Does it return anything? If so, what?
- Are there side effects? What’s changing?
- When is the code used? What other code depends on it?
- What would break it?
- Are there any native language methods being used that you’re unfamiliar with? (If so, definitely take time to note and later lookup these methods, this will help you improve both your reading and your writing)
After reading someone’s code it’s normal to have a few questions for them. If you’re looking at the code of someone you know, ask them! (I recommend asking in a nice way, developers can be defensive about coding decisions they’ve made). If you’re reviewing code on github, you can leave a comment or ask a more general audience such as /r/whichEverLanguage.
Whenever possible, ask questions, do live code reviews and practice pair programming.
And when all else fails, practice reading code by reading your own first.
