Topi Kettunen

Code Reading

Code reading has always been an activity I’ve just done without 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. The 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? Overall, it seems pretty odd to me. Seibel made a great comparison regarding this when he compared programmers to novelists, where if a 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 by doing this, I’ve received a long list of different lessons, ideas, and patterns, which I’ve utilized frequently in most of my work after these revelations.

Pattern Matching

One of the most significant benefits I’ve learned while reading code is that you can 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 comprehending a large open-source project simultaneously 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 parts 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 can abstract the bread and butter out of the program and utilize it however you 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 quickly test how well you understand the foreign code.

Code as a Literature Medium

Many 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 machines second. An excellent example 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 coloured 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 am not interested 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 dissect it sharing the findings with the rest of the group. This dissection done by someone other 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.