Read the title before the text

Sean Goedecke published an interesting article about how to read code. What stood out to me was the idea of going through it in layers. He describes a technique where you first “figure out the overall structure, then the sub-structure, and then finally the details.”¹ That approach reminded me of a paper by Bransford and Johnson (1972) about the importance of context for understanding.²

Instead of describing their results, you can do a self-experiment to get a feeling for that relationship. Read the following text. Then close your eyes and imagine you’re telling a friend about it. How well do you think you understood it? After that, go to the footnote³ to read the text’s title.

The procedure is actually quite simple. First you arrange things into different groups depending on their makeup. Of course, one pile may be sufficient depending on how much there is to do. If you have to go somewhere else due to lack of facilities that is the next step, otherwise you are pretty well set. It is important not to overdo any particular endeavor. That is, it is better to do too few things at once than too many. In the short run this may not seem important, but complications from doing too many can easily arise. A mistake can be expensive as well. The manipulation of the appropriate mechanisms should be self-explanatory, and we need not dwell on it here. At first the whole procedure will seem complicated. Soon, however, it will become just another facet of life. It is difficult to foresee any end to the necessity for this task in the immediate future, but then one never can tell.

Back at university, our professor did something similar in class. I still remember going from “what the heck” to “oh, that’s what it’s about.” Suddenly, the text made sense, all because of a title. I hope it worked for you too.

In Bransford and Johnson’s experiment, the group that received the title before hearing the text showed better comprehension. Analogously, if you have an understanding of the overall structure of the code, you’re in a better position to understand the sub-structure. Reading code in layers is much like reading the title before the text.

We could also extend this view a little. Context and titles are mainly proxies for familiarity. If you were an alien from another dimension, that title might not have helped you understand the text at all. The same goes for reading code: if there is nothing you’re familiar with (because you’ve never read a line of code before), a higher-level structure isn’t helpful.

But maybe “reading in layers” is really about finding familiar ground. When something is unfamiliar, zoom out until you find a concept you know, or can get to know, and then work your way down until you understand what you were after. For code, that might be the architecture, a design pattern, or the name of a function.