Code reading is an essential skill in any situation or field of software development. But many software engineers feel they're not good at code reading. Additionally, many software engineers have also experienced situations where it is not easy to read and understand code.
For example, when we face code where a function doesn't correspond to what we expect by its name, or there are too many conditional branches, we feel uncomfortable or irritated. When we're analyzing a bug, we open 3 or 4 files and trace through methods or classes. Have you forgotten the code that you have read once in such a situation?
These problems have any causes that make it difficult to read and understand code. Because we don't provide solutions for these causes, we may not feel good about code reading. Have you considered what types of causes there are behind a difficult situation for code reading?
What types of causes are there behind code reading problems? #
The causes behind code reading problems can be classified into 9 types.
- Bad code
- Lack of fundamentals of syntax
- Unfriendly environment
- Unused functions of tools
- Lack of mastery of code reading tips and techniques
- Clutter and disorganization
- Time limits and overwhelmed amount of code
- Lack of documents
- Lack of background knowledge
Some causes are clear while others are perhaps unexpected. It is important to recognize a cause when a code reading problem appears in front of you. Let's take a look at each cause in detail.
1. Bad Code #
Bad code means the code includes something troublesome from the viewpoint of readability. An example is the code where a function doesn't correspond to what we expect by its name. Spaghetti code is also classified as bad code. Too many conditional branches or too deep nests lay a burden on us, and then we're in trouble reading code. You can find a lot of anti-patterns and solutions for readability in The Art of Readable Code.
2. Lack of fundamentals of syntax #
A lack of fundamentals of syntax can express "not good enough to learn the syntax of a programming language". Some junior engineers tend to learn a tutorial or a hands-on approach at first rather than a fundamental textbook mainly based on syntax. Therefore, they may learn only parts of the syntax of a programming language, not all. It is vital to understand the syntax thoroughly to read code.
3. Unfriendly environment #
It is important to arrange an environment for code reading. Do you leave your environment unfriendly? There are a lot of files or apps open on a small display, like on a laptop. Too small fonts or variable-width fonts. Frequent noisy notifications. Such an unfriendly environment distracts attention from code.
4. Unused functions of tools #
The ways to use a code editor can cause discomfort or frustration. Without enabling multiple panes, repeated tab switching irritates us. If the code we're reading doesn't follow coding conventions, we should use a code formatter function. A code editor has a lot of functions, so it is worth making the best use of them for code reading.
5. Lack of mastery of code reading tips and techniques #
This cause is different from a lack of fundamentals of syntax. Code reading tips and techniques are ways to get information or hints to understand code or software itself. For example, inferring a function from its name, reading test code in advance, and checking directory trees and file names. Other engineers don't often teach these tips and techniques, so it is hard even to notice a lack of mastery of code reading tips and techniques. This lack badly affects the productivity or efficiency of code reading, especially when there is less information.
6. Clutter and disorganization #
The more code we read, the more complexity we face. As a result, we get confused and stuck in the middle of code reading. This problem is caused by not organizing the information we get from the code. Ideally, we should organize the information, or associate it with other information and knowledge, right after reading a piece of code. But it is not easy to do so every time.
7. Time limits and overwhelmed amount of code #
Apparently, these constraints affect the performance of code reading. We don't often have enough time to read all the code we need to understand. In such a situation, we have to select the code to read from a large amount of code. The selection limits the information we can get and causes a lack of the information we should have gotten. Of course, mental stress and strain also disturb code reading because of time limits and an overwhelmed amount of code.
8. Lack of documents #
In most cases, documents are lacking. There isn't even a short comment that helps us understand the code. The former engineers who should explain the code to us are often absent. These are examples of a lack of documentation. Because documents include a lot of information to help understand software, a lack of documents slows down code reading.
9. Lack of background knowledge #
Background knowledge covers a wide range of information, from a framework's conventions to hardware constraints to a contract with a customer. If we have enough background knowledge in a project, it's no problem reading code. But if not enough, it is very difficult to find what background knowledge is lacking, and therefore we get stuck for a long time without knowing the reason.
Conclusion #
When we find it hard to read code, there are 9 types of causes behind the situation. Difficulties in code reading arise from various causes like bad code, a lack of fundamentals of syntax, and so on. How many causes have you already known?
Once a cause is found, you can introduce a solution. If you leave some code reading problems unsolved, let's try to identify which types of causes they fall into and find solutions to build a feeling of "being good at code reading".
Read it easy is a desktop app that helps with unused functions in tools and a lack of mastery of code reading tips and techniques. We recommend it if you want to improve your experience of code reading.