How to Read Code
It was about a month since I finished my Computer Science degree. Freshly joined my new team, I sat at my desk with a laptop in front of me. Staring back right at me was the project assigned to me. It was Stockholm, our own warehouse management system. Stockholm is such a big project. I don’t know where to start reading it. Going straight to the code didn’t help. It showed “how it does something,” I didn’t get the “what it does.” I was confused.
Back when I was pursuing my undergraduate degree, I learned how to write code. Each term, there was at least one course that made us write a simple project. But with all the class I have finished, I believe I never learned how to read a big project.
Don’t get me wrong, it’s obvious that writing code is essential. We — software developer — got paid for writing code, not reading one. But, our job involves not only writing code, we also read code. Thus, I believe developing our reading skill will help. At least to avoid being paralyzed when meeting new code.
But how? How to improve our code reading skill?
The right book for the right problem
As I reflect on that question, I remember that I had met a book that answers a somewhat similar question. It’s a beautiful book by Mortimer Adler. The title is “How to read a book.”
Adler tells us how to read a book — not code. But I think that what we can do for a book, we can also apply it to code. Because a book and code are quite alike. Both try to convey something. With a book, we have an idea or story. With code, it’s about how to solve a problem. We call it “algorithm.”
In his book, Adler classifies reading skill into 4 different levels. The levels are ordered with a hierarchy. Competency on a level is required before advancing to the next level. So, here’s my interpretation, on how to read code, starting with the most fundamental one.
Level I: Elementary Reading
This is the starting point of any reading. In this level, we try to be accustomed to the language. First, one should become familiar with the writing system used. Fortunately for us, most of the code is written using a Latin alphabet (and I can safely assume that every programmer can read the Latin alphabet.) Thus, it’s not necessary to learn a new writing system to write code. Unless you’re playing with an esoteric one like Piet.
After the character, we continue with grammar and vocabulary. Recognizing the letter is not enough. No matter how good your ability to read an English book, unless you know French, you won’t be able to read any French book. Despite both use Latin alphabet.
In programming, grammar and vocabulary reflected in syntax and keyword. We should make us familiar with the keywords like if, while, for, var, class, throw and how to use them. We learn to adhere to the compiler or the interpreter, whoever reigns there. So as a result, we can speak the programming language fluently.
Level II: Inspectional Reading
Inspectional reading is all about understanding the general structure. Adler suggests us to go through the table of content, read the index and skim the book. Adler even uses some unusual words like “Superficial reading”; just read and keep going even if there’s something we don’t understand. This is not the step when we digest the book. This is the time to “index” the book. Or in our case, the code.
A code’s structure is reflected on how its overall folder, files, and function are placed. Fortunately, most of the projects follow pattern. We don’t need to learn a new kind of structure every time we face a new project. People call them architectural pattern and design pattern. Those patterns are proven to work in a certain condition. People learn from each other; these patterns are used again and again. Having a familiarity with the pattern used will help on our journey exploring the code.
Another structure-defining mechanism in a project is the programming framework. A framework usually has a guidelines that defines the files structure and naming convention. So, having a certain level of familiarity with the framework used will also benefit us.
Level III: Analytical Reading
“Analytical reading is preeminently for the sake of understanding.”
Finally, we got to the part of understanding. To interpret a book, Adler suggests that we should first come to terms with an author. It means that we should understand the vocabulary used in the book. Without understanding the terms, analytical reading is impossible. Because as Adler has said: “For a term is the basic element of communicable knowledge.”
With code, the terms are borrowed from the business domain. It will appear many times in the variable and function’s name. Therefore, having familiarity with the business domain will help us to understand the code.
After we know the terms, then we go to find and understand the book’s arguments. Luckily for us, code is like a recipe. We don’t need any additional effort to find the argument; everything is written as it is. What we need to do is to understand the algorithm. Which now will be easier; since we have mastered the structure and the vocabulary.
Level IV: Syntopical reading
This is the highest level of reading possible. Instead of a single book, we deal with multiple books. At this level, we become the active agent. We question multiple books on the same topic to assist us to increase our knowledge in this topic.
The first step is to make the book come to terms with each other. It’s not so uncommon for two (or more) different books to use a different word to express the exact same concept. As the moderator of this dialogue between books, it’s our job to rephrase the idea in such a word that best suited to our question. After the terms are established, we can begin to analyze how each book state their opinion on that very question. At the end of the discussion and analysis, we will finally find the answer to our question. With having a deeper knowledge as a result.
Unfortunately, I can’t share much about code here. My experience is yet to reach this level. I haven’t met a situation where I need to compare projects. But, I caught a glimpse of what this level looks like on what my senior does.
When our team was discussing the roadmap of Stockholm, my senior share what he learns after comparing Stockholm with another warehouse management system. He shares what Stockholm lacks, how the other service does better than us, and how it resolves the problems that we have. It’s all about asking other projects how to solve our problems. And to do that, I believe he have a deep knowledge about warehouse management system.
Learning Beyond Technical
We can’t rely only on technical knowledge to become a better developer. Technical knowledge is the first step in our journey; having the business knowledge will accelerate it. Because ultimately, software is created to solve people’s problem. Without understanding the problem accurately, we can’t maximize our help.
As I reflect on this journey, I realized that my problem is that I haven’t fully understood the business process of warehouse management system. We shouldn’t work harder, we should work smarter. It won’t matter how hard I push myself to learn the language or framework. Instead, the more important thing to do is to understand the warehouse management system: what problem it solves and how it solves the problem. Without that knowledge, I will still get paralyzed in front of Stockholm, and never give a meaningful impact to my team.
The exciting thing for me is that Stockholm will undergo a revamp. Stockholm is so big that it contains two different modules: the warehouse management system and inventory management system. The plan is to split Stockholm into a smaller system. The first step is to create a new independent inventory management system. Then create the new warehouse management system. And finally, say our farewell to Stockholm. I hope I can join this project so I can accelerate my learning on the business domain. Otherwise, I'll just read a book about my inventory management or warehouse management; with Adler as my mentor.
