Code reading is an essential skill in any situations or fields of software development. But there are a lot of software engineers who have a feeling of not being good at code reading. Additionally, any software engineers have also experienced various situations in which it is not so easy to read and understand code.
For example, when we face the code that a function doesn't correspond to what we expect by its name or there are too much conditional branches, we feel uncomfortable or irritated. When we're analyzing a bug, 3 or 4 files are opened and we're tracing some methods or classes. Have you forgot the code which 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 any solutions for such causes, we may not get a feeling of being good at 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 readablity. An example is the code that a function doesn't correspond to what we expect by its name. Spaghetti code is also classified into bad code. Too much 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 of 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 of junior engineers tend to learn a tutorial or a hands-on at first rather than a fundamental textbook mainly based on a syntax. Therefore, they may learn only parts of the syntax of a programming language, not all. It is vital to understand a syntax exhaustively in order 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 opened in a small display like in 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 text editor can cause uncomfortableness or frustration. Without enabling multiple panes, repeated switching of tabs makes us irritated. If the code we're reading doesn't follow coding conventions, we should use a function of code formatter. A text editor has a lot of functions, so it is worth making the best use of its functions 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 the way to get some information or hints so as to understand code or software itself. For example, inferring a function from its name, reading a test code in advance and checking directory trees and file names. These tips and techniques aren't often taught by other engineers, so it is hard to even notice a lack of mastery of code reading tips and techniques. The lack badly affects productivity or efficiency of code reading, especially in the case of 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 just 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 got. Of course, mental stresses and strains also disturb code reading because of time limits and overwhelmed amount of code.
8. Lack of documents #
In most of the cases, documents lack. There isn't frequently even a short comment which helps us understand code. The former engineers who should explain us to the code are often absent. These are the examples of lack of documents. 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 conventions of a framework 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 lacks and therefore we get stuck for a long time without knowing the reason.
Conclusion #
When we feel hard to read code, there are 9 types of causes behind the situation. Difficulties of code reading arise from various causes like bad code, a lack of fundamentals of sytax 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 are classified into and find solutions in order to have a feeling of "being good at code reading".
Read it easy is a desktop app as a solution for Unused functions of tools and Lack of mastery of code reading tips and techniques. We recommend it if you improve your experience of code reading.