The Art of Code Reading
When I began my software engineering carrier, I didn’t know how to read code. I mean, not at all. And I am not even talking about code written by other people. I even struggled to understand my own code if it was more than a few weeks old. Back then, I didn’t even realize how big of a blind spot this was because my code mostly worked, and if it didn’t, I would eventually figure things out.
It all changed one day when I got stuck debugging an issue. Because I didn’t know how to proceed, I decided to ask one of my co-workers for help. I explained the problem to him and saw him dive in the code of a library we used. I knew this code existed but had never dared to open it - it was not “ours”. He would quickly jump from file to file using a combination of grep and a basic (no syntax coloring) text editor and in less than 15 minutes he pointed to the line that was likely the culprit. His diagnosis was correct and I started thinking that perhaps I should find a different career.
After some deliberation, I decided that getting better at reading code was a better option than changing careers.
Learning to read code
The best way to learn to read code is to practice (i.e. to read a lot of code). It is not as easy as it sounds. Reading code is much harder than writing code as it it requires piecing together the context from various parts and putting yourself in the shoes of the original code author. But the hardest part is to not give up when you don’t understand the code you’re reading. This will happen frequently because often you just won’t have enough context when reading unfamiliar code. In many cases, however, you don’t need to understand everything - you need to understand enough to fix your bug or get the main idea.
With time, you will gain enough experience to know when you understand enough to move on. You will also be able to quickly identify which code is relevant to what you are trying to accomplish and which code could be skipped.
If you work as a software engineer, your job gives you plenty of opportunities to learn to read code:
code reviews - this is the easiest way because you are already familiar with the code; you can also talk to the author if you have questions
debugging - try stepping into code outside your area of ownership like frameworks or libraries you depend on (hint: in Visual Studio, disable the “Enable Just My Code” option which is on by default)
dependencies - read code of your dependencies to understand how they work; this can also help you discover more optimal ways of using them
And there is also GitHub with its thousands of repositories solving problems of all shapes and sizes. You are guaranteed to find something that will interest you and dive in. GitHub projects can train you not only in reading code that you are not familiar with, but also in understanding code written in languages that you don't know very well or at all.
What are the benefits of having good code reading skills?
Getting better at reading code is an investment that will pay dividends for years to come. Here is how:
Getting up to speed when changing jobs or teams will be smoother and faster.
Code reviews will take less time.
Understanding bugs and fixing them correctly the first time will be easier.
Knowing how your dependencies work will help you come up with better designs.
Your debugging will be more effective, especially in cases where you deal with code you can't debug directly (e.g. missing debug symbols, decompiled code, etc.).
If you feel reading code is not your thing, think again. It might take some time to pick up this skill, but I promise it will serve you for years.
Thanks for reading,
- Pawel