Reviewing Felienne Hermans’ _The Programmer’s Brain_

One of the things I’ve been tasked with at the day job is to work on features in a codebase. The implementation language is all JavaScript, but it uses a lot of once-trendy libraries and frameworks. These libraries and frameworks increase the complexity of the entire codebase in ways that are good for companies that devote multiple teams to a codebase like this. However, these architectural decisions make the whole thing needlessly complicated for our needs. No more than two people have ever worked on this pile of code at the same time.

At any rate, once I became the lead programmer on it, a number of problems cropped up. It took me for-fucking-ever to get what seemed like even basic things changed. I was able to explain that 90% of the effort was in navigating the codebase and understanding it and figuring out where to apply fixes, but it wasn’t obvious to me how to get better, or at least faster, at this. I intuited that I was being overwhelmed by everything that I was trying to keep in memory and it felt like I needed to hold like 20 things in my head at once when I could only hold 5–7. My bigger problem was that it wasn’t super obvious how to fix, or at least ameliorate, this.

As time went on, I found a few techniques that did seem to help me run around in circles less:

commit the working copy less often, so I could see the “this has been changed” colors in the sidebar of Visual Studio Code

pin an editor tab for the file that contains the list of routes

pin an editor tab for the file that contains the API

whip out giant sheets of graph paper and draw diagrams of parts of the codebase that I’m trying to understand

add JSDoc type annotations to functions I was working on, which helps Visual Studio Code understand the types of things just as well as TypeScript types

have one TaskPaper file per issue, where I have the thing be a write-ahead log (inspired by journalled file systems) and can just mash ⌘D to mark a task done

use Alessandro Fragnani’s Bookmarks extension to remember where the important parts of the codebase are to whatever problem I’m working on at the moment

use Eric Amodio’s Restore Editors extension to save my tabs’ layout when switching from one task to another

That made easy things easy and medium-difficulty things hard instead of intractable.

Still, my ability to get stuff done was still too damn slow. I mean, everything that I was doing very much seemed not-hard, at least after I was looking at what I’d been doing in the final pull request, but it was taking me something like 10x the amount of time to bang these features out compared to more senior colleagues.

(As an aside, anyone who claims that “10x programmers don’t exist” or “100x programmers don’t exist” is, at best, ignorant, and most likely a liar.)

⁂

I’ve been listening to Software Engineering Radio for years now, and it’s a podcast where people go to plug their recently-released books. However, one of the hosts was being interviewed as a guest — she had recently come out with _The Programmer’s Brain_, and was on the show to plug it.

I thought that this would be probably the best accelerant I could get my hands on, so I got the book and…well, it took me a while to finally devote the time to reading it.

It is superlatively well-structured. It has four parts: reading code better, thinking about code, writing better code, and collaborating on code.

Each chapter is also structured nicely, and is almost optimized for notetaking in Markdown.

This is what the headers in my notes look like:

Fourth-level and fifth-level headings are in all caps inside the book, but it’s refreshing to have not only sentence-case titles, but also no punctuation between the chapter-and-section dotted numerals and the section title.

If I ever write something long in Typst, I’ll probably go for a section-numbering and -titling style like this.

⁂

The biggest insights I got out of the book are how memory works. There are three major types:

working memory, which only holds like 4–7 things

short-term memory (STM), which only holds like 4–7 things and holds things like identifier names and data structures

long-term memory (LTM), which holds pretty much everything else and doesn’t seem to outright forget anything, but recall can become more difficult over time

I definitely ran into the limits of my working memory all the time. I’d want to look up the ultimate source of some value, get three components away from where I was, and then…dammit, what was I looking for, again?

(You’ll probably notice that there’s way more cussing in this review than has been in the entirety of Scrawlspace to this point. This is a deliberate stylistic choice.)

There’s also three types of cognitive load that one might have on his working memory:

intrinsic load (from how complex the problem is)

extraneous load (what outside distractions add to the problem)

germane load (load caused by trying to archive your thoughts to your LTM)

So if you actually want to learn things, you’ll need to keep your intrinsic+extraneous load down to give yourself room enough for the germane load.

Because your bottleneck will likely be your working memory, the best strategy is to try to stuff as much information in your LTM in nicely-grouped chunks as soon as possible. With more information nicely arranged in your LTM, you’ll be able to free up space in your STM, which will give your working set room to actually solve your problems instead of trying to keep track of still-new-to-you minutiae.

OK, so how do you get stuff in your LTM? There are two kinds of things in there already:

procedural memories (aka implicit), like tying shoelaces or riding a bike

declarative memories (aka explicit), like how Nixon was reelected in ’72 or how a for-loop goes in Go

Declarative memories themselves have two types:

episodic (memories of experiences)

semantic (6 × 7 = 42; grindable with flashcards)

Oddly enough, experts rely on episodic memory more than you might expect.

⁂

So, after reading the book, what will I do differently for this codebase?

First, I was moderately pleased to see that I had been doing some of the things Hermans recommends. On the other hand, I was kind of worried after a few chapters that I’d already be doing all the tricks, and there’d be no good novel advice left for me.

All that said, the winning strategy, at least for this codebase, is to shove as much as I can into the LTM as possible to free up space in the short-term memory. Plus, the more I shove into the LTM, the more I’ll be able to think of collections of discrete things as opaque chunks, and the chunking will help compress the number of things I keep in my head all at one time.

Hermans suggests using flashcards. I reinstalled Anki.

I generally don’t have trouble with JavaScript constructs, although I could stand to go through Promises Training to go from novice to intermediate.

I’ve been transitioning from using ⇧⌘F to find in all files, to pressing ⌘P to type in the name of the file that I’m pretty sure exists and has the function or component I want. I’ll keep doing that more. Trying to remember something helps it stick in your mind, so it’s important to at least try to pull the memory out of your mind.

I could stand to write down more documentation of where the important parts of the codebase are.

The decks are cleared for the germane load when I’m reviewing a pull request that I’ve made, so I’ll lean into taking my sweet time to review my own pull requests for nontrivial changes.

I’m not sure I’ll print anything out to understand stuff, mainly because I have a debugger set up for this codebase. Still, this isn’t going to be the only codebase I’ll ever end up working on.

There are other parts of the book that are focused on green-as-grass novices and the final chapter is aimed at people who are trying to speed up the onboarding process for new programmers to a codebase, but this is what I thought was most important.

Reviewed late November, 2023.

References:

JSDoc, a standard for documenting types in JavaScript code that VS Code can use

TaskPaper, a text editor designed to make keeping track of tasks fast and easy

write-ahead log

Alessandro Fragnani’s Bookmarks extension for Visual Studio Code

Eric Amodio’s Restore Editors extension for Visual Studio Code

Software Engineering Radio

Typst, a PDF-generating program similar to TeX, with an optional online collaborative-authorship that I’ve never used

Scrawlspace, 2023 edition

Anki, a spaced-repetition flashcard app

Promises Training

⏚

Home

Hi! I’m a one-pixel invisible tracking image! View me to let my webmaster know you’ve scrolled through the entire page!