Code reading

23rd of June, 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 as 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. His interviewees tended to be unanimous that code reading is very beneficial. Still, while reading his interviews, it left a picture that the practice itself seemed to be lacking even within those heavyweight programmers. Exception in this being Brad Fitzpatrick and, obviously, Donald Knuth. If these 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 ready 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 received 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.

Pattern Matching

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. Furthermore, 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 pattern matching helps understand the whole project under study itself. It would be best to try to comprehend a large open-source project at once but in small pieces. Then, when one of these pieces is understood, it can help tremendously understand the other pieces.

Benefits of reinventing

It can often be pretty hard to understand the functionality of some part of an extensive program 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 say that code is not literature because you read it differently from 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 to 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 writing 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 grew used to colored text. Of course, I might be a 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 grasp the whole structure better. 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 try some code reading clubs 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 dissecting the main logic behind it and discussing it. However, 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.

If you have any questions or suggestions, write to topi at topikettunen dot com.

Tags: computers, programming