When fixing bugs or adding new features, we read source code to gather information and understand how the software works. But do you jump straight into the source code? Or do you read some documentation first?
It’s possible to find everything you need by reading the source code alone, but it’s not always easy. Wouldn’t it be nice if we could always find the answers we need by reading just a dozen or so lines of code?
To make code easier to read, this article explores the benefits of using documentation alongside source code, the problems that can make documentation less useful, and practical ways to overcome them.
The Benefits of Reading Documentation Alongside Code #
The purpose of code reading is to understand software. We examine the implementation to understand the overall structure of the software and the steps involved in each operation. Documentation, on the other hand, is written to make software easier to understand. In other words, both code reading and documentation help us understand software. So, why not make use of documentation when reading code?
Reading documentation before diving into the source code, or checking it when you get stuck, can be an effective way to understand software. There are three main benefits to reading documentation alongside code:
- It makes the software easier to understand.
- It reduces the time needed to understand the software.
- It helps prevent misunderstandings and incorrect assumptions.
Our goal is to understand software as quickly and accurately as possible. Documentation can be a valuable tool for achieving that goal, so let’s make better use of it.
What Kinds of Documentation and Resources Are Available? #
When reading code, some of the easiest resources to find are:
- Comments in the source code
- README files
- Official documentation
- Requirements specifications
Other useful resources include:
- Technical specifications and design docs
- UML diagrams
- Simple architecture diagrams and relationship diagrams, such as ER diagrams, including hand-drawn ones
- Emails and messages on Slack or Discord
All of these can provide useful clues when reading code. They may not always be available, and they may not have been written specifically to explain the implementation. Still, they’re worth checking if they can make the difficult work of code reading a little easier.
Most of us probably use these resources regularly. But how often do we turn to them when reading code? We might read a README to learn how to use a project, but do we go back to it when trying to understand the source code? Sometimes we even skip comments while reading the code.
We know that documentation can help us understand software more quickly and accurately, yet we don’t read it as often as we could.
Why Don’t We Read Documentation When It’s So Useful? #
If we know that documentation can help us understand software, why don’t we read it more often? Part of the answer is that documentation itself has some problems.
- Low reliability: It’s hard to tell whether a document is worth reading before looking at the code.
- Low availability: We can’t always expect to find a useful README or a well-written comment exactly when we need one.
The first problem may be particularly important. Based on experience, we may have come to believe that most documentation is of poor quality and isn’t worth reading.
There are probably other reasons as well.
For example, when fixing a bug, we often start by checking the error message and jumping to the code where the error occurred. In this workflow, there’s no obvious step for reading documentation.
Once we start reading code, the task itself can be so demanding that we spend all our energy just trying to follow it. We become so focused on what’s in front of us that it doesn’t even occur to us to look away and check the documentation.
These problems with documentation, combined with our usual code-reading workflow and the difficulty of code reading itself, may explain why we’ve developed a habit of not reading documentation.
How to Make Documentation Part of Code Reading #
Let’s start with a few simple changes to break the habit of ignoring documentation.
As mentioned earlier, you may have decided to skip comments because you’ve had too many bad experiences with poorly written ones. However, documentation that many programmers have seen, such as README files and comments in open-source projects, tends to be more reliable. Like the source code itself, it often benefits from review by other developers.
Why not start by making it a habit to read README files and comments in open-source projects, at the very least?
When you get stuck trying to understand something through code reading alone, try going back to the basics:
- Skim through comments across several files.
- Go back and reread the relevant sections of the README.
- Check the official website or documentation.
At first, this may not come naturally. When you get stuck, try asking yourself, “Is there a clue somewhere else?” Make it a habit to look for clues outside the source code.
After all, asking someone who knows the code better than you is probably something you already do when you’re stuck. Why not add checking the documentation to your list of options?
There’s also a simple and practical technique you can use when good documentation isn’t available: create your own lists of functions, variables, and constants defined in a file or class.
Function and variable names often reflect part of what they do. Just listing these names and comparing them can reveal a surprising amount of useful information.
Stopping your code reading to create a reference document might seem counterproductive. But remember our goal: to understand software as quickly and accurately as possible. Sometimes, you need to slow down to speed up. This approach is worth trying.
By developing the habit of looking beyond the source code and consulting documentation, we can reduce the effort required to read code and get closer to our goal of understanding software quickly and accurately.
Conclusion #
We’ve looked at how documentation can support code reading. Reading documentation alongside source code can help us understand software more quickly and accurately.
Past experiences may have made some of us reluctant to check documentation. But simply keeping the option in mind—“Maybe there’s a clue in the documentation”—can help us get unstuck when code reading becomes difficult. It can also reduce the stress and frustration we associate with reading unfamiliar code.
Let’s make reading documentation a regular part of our code-reading process.