How to read a code

You run through the subsystems in the code and check for impact, make the change and test it to verify you haven't missed anything. But greenfield projects where you will be the sole author are exceedingly rare in my experience.

More common is to be thrown into an ongoing project. Or even more common is to be added to a project because key personnel left. With no time for handover. So how do you get up to speed and make changes with confidence then?

I started out like I guess most people start out - read one file, move to the next and hope it makes sense after a while. And it does. But it can be a very long time with embarrassing disasters before that confidence comes.

Disasters usually set back the confidence a notch or two. Realizing this I started to research and experiment on how you can achieve confidence in your changes in less time.

Mental models

I've mentioned mental models before as it's prevalent in anyone who has mastered a subject well enough.

Let's nail the definition down first: A mental model is a simplification or an abstraction of a system that you carry around in your head. It's a few principles / images / sounds / phrases that acts as a stand-in for the actual system.

They're not the real thing, but they're close enough to be correct 95% of the time. When someone asks you "can we add feature X?" you first say "no" and then you go to your mental model of the system and investigate the impact to check that you are correct.

In software the materialization of these mental models is often a drawing with boxes and arrows or pseudo-code and call-charts depending on the level you're describing.

Why the fuss on mental models?

Trying to understand a new code-base is trying to get a mental model of the program into your head. When I have a decent mental model of it I can judge the impact of changes made and be sure the change does only what I intend it to.

So this will be our end goal. Building a fairly deep understanding of the architecture of a program. All good but nothing groundbreaking so far. This is what everyone must do in order to safely do changes - even reading one file and moving on to the next until it makes sense builds a mental model.

But it's slow. So let's see how we can supercharge this.

Active recalling

I've made a vow - which I mostly stick by - of never copy pasting code. It's a trick I learned from Zed Shaw in his course "Learn C the hard way". I'll type it in myself without looking at the original.

Then I go back and forth and diff it with the original code until they match. Why? It builds better understanding and retention. By typing out the code I've just read from memory I'm forcing my brain to pay better attention.

And in this lies the wonderful bootstrapping process of understanding. Actively trying to recall something will at the same time increase your understanding of it. The process of trying to remember things from raw recall has been dubbed just that: active recall.

There's been plenty of research on learning for decades on active recall and the trick from Zed Shaw is one take on it, you force your mind to recall without looking.

The generation effect

There's another trick to more accurately recalling the correct answer called the generation effect. I stumbled upon this in the book "Make It Stick" by Peter Brown.

The gist of it is if you're forced to come up with an answer to a question even when you are dead wrong pays off. Studies have shown that by making students guess the answer to a question even when the subject is totally unknown boosts the retention of the correct answer once it's revealed.

This sounds right up our alley since the code-base is largely unknown. We can leverage this effect and make the learning more efficient by guessing what parts do before actually reading them.

How to read a book

The last source to super-charge our learning is from a book called "How to read a book" by Mortimer J. Adler. The book details how to read a book. Well duh, I thought. But it's well worth a read.

I was very surprised at the methodical approach and how unstructured I was prior to this. Learning a book and learning a code-base have (un)surprisingly much in common.

This book will be the driving force of the processes of learning the code base with the super-charged methods above sprinkled in. The book outlines four levels of reading.

I'll include a shorter version of the three first levels as they are of interest to this post.

Three first stages of reading a book

First level - Elementary reading - in which the reader is not hindered by the language (i e is fluent in reading the language of the book). At this level the reader reads a book cover to cover not giving it much thought of the structure or if it's a book worth reading before the end is reached. 

This is the most common level to read at. Not surprisingly according to the authors there's more efficient ways (and more work) of really understanding a book.

Second level - Inspectional reading - in which the user tries to find out the most of a book in a limited time by asking the question "What is the book about, as a whole?". 

The first phase includes skimming, reading the back and front-matter, the TOC, the index and a few selected pages here and there.

The second phase is reading the whole thing on a timer not stopping to understand details. This is because you most certainly will get lost on details. There is no big picture to make sense of the details yet.

This matters even more when reading code.

Third level - Active reading - in which the reader understands the book by bottoming-up from finding the most important words the author uses all the way up to the arguments the author has used and how well the author answers the questions the book set out to answer.

As you can see the process involves first top-downing the book and then bottoming it up until you grasp the whole. The top-down process involves scanning for the important bits and the bottoming up connecting what you've deemed as important to the rest of the book.

This makes sense. We learn best by first going after the general major concepts. Only then does the details make sense as you can associate them with the major parts.

Being an active reader

It's not enough to merely read it in this way. An active reader asks and tries to find answers to questions. By doing this we increase difficulty making the understanding and learning even deeper.

An active reader hopefully writes down the findings and answers to questions posed as writing things down makes them stick better in your head. I'll assume that there is no up-to-date documentation on the project you are about to learn.

I'm hard pressed to recall one instance where the documentation was good enough to actually help understand the code-base. The perils of documentation is akin to that of a commentary in the world of books which the authors warn against.

A commentary is a book that comments or summarizes another book. You're getting someone else's view on the project. It will probably be outdated. If there is documentation be very sceptical of its correctness and don't rely on it until it's proven correct.

This equates to RTFS.

Assuming elementary level

Reading below the elementary level is not being fluent in the language of the book. Same goes for the project you want to learn.

If you don't know the syntax of your language then stop right here, learn the syntax and then come back. I've wasted many hours trying to understand both language and projects at the same time.

It fails for the same reason that inspectional reading succeeds - you'll get caught in details and you won't even know if just a feature of the language or a significant property of the code you're reading.

What problem does it solve?

Following the outline of the second and third level of reading let's apply that to learning a code-base. Bottoming-up a code-base is the default. To be able to top-down something you need to know what's on the top and what's on the bottom.

To find that out we'll start with the inspectional reading phase. In the book the question we're trying to answer is when doing inspectional reading is "What is the book about, as a whole?". When learning the code base we're going to slightly alter that question into: "What problem does it solve?"

So - first grab a piece of paper and pen. Write that out as a heading. This is a good way of priming your already existing information. And to add to the excitement of priming your mind add in two questions: "How would I implement this?" and "What do I know of the domain"? 

Then without looking at the README or similar - just write down what you know about the project beforehand.