Code ReadingFebruary, 2021
Code reading has always been this activity that I’ve just done without really giving any thought to it. But despite this, now, when I look back at this habit, I see it is immensely beneficial. This habit caught my attention when I was reading Peter Seibel’s book Coders at Work, in which there is a section where Peter asks about code reading from his interviewees. It tended to be unanimous amongst his interviewees that code reading is very beneficial. Still, while reading his interviews, it left a picture that even within those heavyweight programmers, the practice itself seemed to be lacking. Exception in this being Brad Fitzpatrick and, obviously, Donald Knuth. If these kinds of programmers speak for this practice but don’t do it in the wild, then who does? This overall, it seems pretty odd to me. Seibel made a great comparison regarding this when he compared programmers to novelists, where if novelist hasn’t read anyone else’s publications, it would be unheard of.
I’ve always enjoyed reading others' source code mainly, let’s face it, to steal some ideas. But doing this, I’ve able to receive a long list of different lessons, ideas, and patterns, which I’ve been able to utilize frequently in most of the work that I’ve done after these revelations.
One of the most significant benefits that I’ve learned while code reading is that you’re able to learn various patterns after a while. Sure, every project might seem cluttered and hard to understand for a while, but when you get the gist of it, you start to realize why this or that has been done the way it is. When you’ve understood some of these patterns, it gets much more comfortable to start noticing them in other similar or not so similar projects. Fundamentally this means the graph of WTF-per-seconds starts getting less and less.
I have also noticed that this kind of pattern matching helps understand the whole project under study itself. It would be best if you didn’t try to comprehend a large open-source project at once but in small pieces. When one of these pieces is understood, it can help tremendously in understanding the other pieces.
Benefits of reinventing
Now, quite often, it can be pretty hard to understand the functionality of some part of a big program just by looking at the code. So quite often, to get a better grasp of foreign code is to reimplement the way you would write it. This way, you’re able to abstract the bread and butter out of the program and utilize it however you might want.
This kind of reimplementing can be quite hard on bigger projects. The best way to reinvent something in those projects is to change something and see changes in the new compilation. For example, try to change some text in some menu or output. This way, you can easily test how well you understand the foreign code.
Code as a literature medium
Many people tend to say that code is not literature because you read it differently than prose. In my opinion, this doesn’t necessarily need to be the case. Overall, code is written for humans first and then machine second. An excellent example of this is Robert C. Martin’s ravings, in which he often recites that the “code should read like prose to be clean”, which I tend to agree with. Another good one is Donald Knuth’s approach with literate programming. However, the latter one is more about embedding code pieces amidst what one could call prose. Nonetheless, this kind of system makes the code much more readable since the writing itself is such a big part.
One thing that I believe makes people think code is not literature is syntax highlighting. I don’t use it. For some reason, I never grow used to colored text. Of course, I might be a little bit biased, but when I turn on syntax highlighting, I tend to focus on the wrong things in the code, making it so that it doesn’t read like prose anymore. Removing syntax highlighting has allowed me to get a better grasp of the whole structure more easily. Is this true, or does it work for everyone? I don’t think so, but that’s how I feel.
Code Reading Club
Based on these thoughts and Seibel’s ideas, I decided to give some sort of code reading club a try in my workplace. Initially, what I had in mind for this kind of club was choosing one library/program per week/month or whatever and then dissect the main logic behind it and discuss it. I quickly realized that this would most likely work since people have different interests in programming. For example, I don’t have an interest in various GUI applications or other frontend technologies, even though they might have some good ideas behind them.
So a much better approach would most likely be that person chooses one library/program and then dissects it sharing the findings to the rest of the group. This dissection done by someone else than yourself could easily inspire you and others to dive more deeply into the code itself, even though it might be a little bit outside your interests. That being said, exploring the world around your circles can be mind-opening since you can easily find new approaches to the same problems that you might face in your work.
I want to give this kind of approach a good try, and I could write some “deep thoughts” about it in the form of a review.