š¾ Archived View for gemini.circumlunar.space āŗ users āŗ adiabatic āŗ words āŗ reviews āŗ books āŗ the-proā¦ captured on 2023-12-28 at 15:38:00. Gemini links have been rewritten to link to archived content
ā”ļø Next capture (2024-05-10)
-=-=-=-=-=-=-
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:
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:
# 8 How to get better at naming things ## 8.1 Why naming matters ### 8.1.1 Why naming matters #### Names make up a large part of codebases #### Names play a role in code reviews #### Names are the most accessible form of documentation #### Names can serve as beacons ### 8.1.2 Different perspectives on naming ā®
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:
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:
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:
Declarative memories themselves have two types:
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
Alessandro Fragnaniās Bookmarks extension for Visual Studio Code
Eric Amodioās Restore Editors extension for Visual Studio Code
Anki, a spaced-repetition flashcard app
ā
