git-fixup

I make a lot of small, frequent commits, checking in every time the code works and has a meaningful change I wouldn't want to lose. Then, if new work gets the code in a tangle or breaks something I don't understand, I can clear the mess by resetting the working directory to latest commit. Tiny and always-working commits also helps git bisect.

Occasionally commits need amending. Some commit in a long list of commits broke a feature or introduced a bug that didn't get noticed. Rather than just add the fix to that long list, I prefer to update the commit that introduced the problem. To do that, I add a commit whose message starts with "fixup", then do an interactive rebase, which allows re-ordering commits and indicating that the fixup commit should be squashed into the commit before it. Then the original commit is cleaner.

While branches are often short-lived enough to rebase the whole branch, it's tricker to rebase when developing directly off the main trunk. One has to find the commit hash for the commit that needs to be amended then run git rebase -i <hash>^. To turn the process of finding a commit hash and rebasing into one step, I use this script:

git log --oneline -50 \
    | fzf \
    | cut -d' ' -f1 \
    | xargs -I {} git rebase -i {}^

That lists the last 50 commits with their short-form SHA and commit message, and pipes them into fzf where you can search for the commit message of the commit you want to rebase onto. Select a commit by moving up and down and/or searching and hitting Enter. Then git rebase -i <hash>^ will run with the commit you selected, which opens your default text editor where you can move the fixup commit to where it belongs in the list, mark it with an f for "fixup", then exit and apply the rebase.

git-regress

When reviewing code that includes tests, I run the tests on my local machine to surface any missing environment variables, potential OS incompatibilities, test flakiness, and sometimes even tests that aren't picked up by the test runner.

I also want to see that the tests can fail. Sometimes the tests run but the assertions are broken, such as the case of the .assertTrue that forgot the () after it, preventing the assertion from actually being invoked. The easiest way to see new tests fail is to undo the application changes the tests are checking.

To undo a branch's logical changes but not its tests, use git diff <some-branch>... -R -- <directories> | patch -p1. That creates a reverse diff of specific files, then applies the changes.

To simplify finding the code to undo then patching, I use this script that gives fzf all the changed files on a branch, which lets me select the files to revert then applies the reverse diff of those files:

mainBranch=$(git remote show origin | grep 'HEAD branch' | cut -d' ' -f5)
toRevert=$(git diff $mainBranch... --name-only \
  | sort -u \
  | fzf --ansi \
      --disabled \
      --bind 'j:down,k:up,q:abort' \
      --preview="git diff $mainBranch... -- {}" \
      --preview-window=right:60%)

if [ -z "$toRevert" ]; then
  echo "No directories or files selected."
  exit 1
fi

git diff $mainBranch... -R -- $toRevert | patch -p1

You may want to add a step after git diff ... that takes the files changed on the branch and includes their parent directories, so you can revert the changes in a whole directory without having to select every file under it.

If you have suggestions for improvements to either of these scripts, or if you have your own scripts that help with your workflow, please email me.

The little guy is a born manager. My friend Joe has a term for that kind of response from a leader. Years ago I was pulled off a project to work on a more urgent project, and during it I wrote some convoluted code that I should have refactored before publishing. When a reviewer called me out, I complained about the rush. The next morning, the project manager left a comment: "You’ve been doing a lot of awesome work Eric! Your contributions, insights, and suggestions have really helped the [project] effort. Thanks!" When I told Joe that story, he called it "affirmation bombing".

Leaders often address complaints with compliments. But when praise is just a tactic used to assuage frustration, it comes across as disingenuous. Worse, it can to backfire if the receiver sees through such praise and interprets it as, "Your negative emotions have given me negative emotions, so I want them to go away. If this bit of positivity doesn't give you positive emotions, you must either hide your negative emotions or go away yourself." Praise can, counterintuitively, deepen a negative feeling.

To keep my praise authentic, I tend to be sparing with it, but as a dad I've had to learn to be more generous. Kind words still have to be spontaneous, not calculated, so I've chosen to get sensitive to what's worth praising. Trying an unfamiliar food. Keeping a screwdriver in the head of a screw.

I've also learned to give myself some kind words. It's easy for me to discount praise, to see it as motivated, to know it's part of a scheduled review cycle, to wish it was more substantive. But rejecting all praise leads to long, dark moods. It's important to recognize compliments from others even if it's sometimes tactical. Rarely is it outright dishonest. Kindness prompted by a complaint is still kindness.

At one company I worked for, we emailed positive remarks from a client out to the whole staff with a subject line of "Nice words". One day I decided to adopt that practice for myself. Whenever someone gives a kind word, even if it was affirmation bombing, or a perfunctory farewell when changing jobs, or an annual review where the boss instructed everyone to review gently, I write it down. Tim Ferriss does something similar with a "Jar of Awesome". I keep a digital version. Every now and then I come across one I'd forgotten. "You have a nice reading voice." "We should all be using your terminal setup." "You've been a huge inspiration to me." "I love the Eric notes." "What you did is how I want this department to behave." "You're probably my favorite writer." I can quote the project lead's original affirmation bomb word for word because I wrote it down in my nice words file.

Some nice words were offhand comments, and while I may still discount a lot of compliments as general politeness, I do write down the things I find myself thinking about later. Fading memory doesn't mean the emotional boost of kind words also has to fade.

When I was a teenager, my father made me read Sean Covey's The 7 Habits of Highly Effective Teens, which used the metaphor of a relationship bank account: you have to make more deposits than withdrawals, and unlike an actual bank account, in relationships a deposit tends to evaporate and a withdrawal turns to stone. The same happens in our relationships with ourselves. For decades we remember an embarrassing moment, a typo in a tweet, a negative comment on a blog post, but we forget the compliments and nice words. Keeping a jar of awesome or a document of nice words is a way to combat that human weakness. Beyond that, documenting the positive things people say about you shows what others perceive to be your strengths, which can provide insight into how you can be your best self.

Sure there are bad days and low moods, but you are doing a good job!

1. Draw to create focus

It's easy to get distracted during a 40-minute or longer talk, but drawing creates focus by distracting the part of the brain that generates distractions. Doodling occupies the hand and the brain's visual processing. Even abstract patterns can serve as memory anchors, but infusing your doodles with content from the presentation locks it even deeper into memory, and it's more fun.

You don't have to be an artist to make sketchnoting fun or memorable. Simple drawings are great. Elaborate illustrations often detract from focus, rather than enhancing it.

2. There are many ways to be visual

Sketchnotes frequently translate a presentation's visual elements into pictures, but many presentations are mostly text. Notes without a visual language can still be sketchnotes. Just capture text in visually interesting ways: make lists look like lists, underline important works, use an accent color for some words, write some words in ALL CAPS. Wrap sentences and fragments to leave room around them where you can write related concepts.

A presentation is given linearly, one word after another, but the ideas have non-linear relationships that benefit from being captured in two dimensions. Paper allows you to de-linearize the content, even if you don't draw any pictures.

3. Use pen and paper

Using physical pen and paper is freeing. I've sketchnoted on tablets, but switching pens and colors is distracting. If the app allows editing—which most do because of the imprecision of stylus input—then it's tempting to clean up a drawing instead of listening. Paper has no distracting notifications or apps, and the battery never dies. You might not be able to erase, but mistakes can be memorable too.

I take sketchnotes on an 8"x5" index card that's blank on both sides. For pens I use basic utensils: a Pilot V5 and an orange felt-tip Paper Mate. Both provide smooth lines. The one fancier tool I use is a Copic N4 marker with a brush tip, to add some color or shadow to drawings, though when it's used up I'll probably look for a lighter shade of gray.

4. Sketchnote for yourself, not others

Sketchnotes are never detailed enough to reconstruct a talk, so they tend to have little meaning to those outside the audience. Even for those who did hear the presentation, your personal notations are likely to be opaque. You might share your sketchnotes with the speaker or other members of the audience, but don't expect anyone to use them as a reference. They're for you. The act of making them is the valuable part. Your memory of the event will be embedded in your own physical movements of drawing and writing. Share your notes in recognition of the time and energy the speaker put into their talk, and as a token of the time the audience spent together, but no one will get more out of your notes than you do.

5. Do it!

You can start sketchnoting without experience, without tips, and without a grand reason. Do it for fun! Do it to enhance your memory of the occasion. Do it to create connection with others.

The purpose of sketchnoting isn't to become a master. You don't need artistic ability or perfect penmanship. The goal is to focus your attention, make you think more deeply about others' ideas, and have and share a memorable experience.

Sketchnoting is a gift to your future self.

(For concrete tips on sketchnoting, see my earlier post and Mike Rohde's The Sketchnote Handbook.)

In the previous post I described a small game and some friction I encountered implementing a basic game loop. The problem was minor, and it would have been easy to ask an LLM to churn out the code. But I didn't, because my goal wasn't really to make a game, it was to learn. The friction created by my approach was instructive. I was cutting against the grain of the problem, rather than working with the grain. I could have forced my way through the quagmire, either myself or with the help of an AI sledgehammer, but I was making the game for fun, and part of the fun is exploring new approaches and adding new tools to my toolbox.

Experiences like that are why I continue to write code more by hand than by AI. When I do ask an LLM to code, it's so I can learn, not to outsource the effort. I have a relationship with the problem and the potential solutions I've collected, not so different from the way a woodworker has a relationship with the material and his tools. A relationship can't be delegated to a machine, even a thinking machine.

The craftsman mindset may become a luxury. Code written by hand may be considered "artisanal". But I love doing more with less, like using curved sections of a tree to make curves in a ship's ribs stronger with less work, and while LLMs are often billed as saving us work, the total amount of work done is usually more. I value craftsmanship, and I still believe technique matters, even when it's slower.

So while I use AI, I don't use it as a substitute for learning. Notation is a tool of thought, and working hands-on with the code is a form of thinking. I write code myself because, beyond crafting software, I'm also crafting myself.

It's implemented in ClojureScript, the UI is rendered with Replicant, events handled with Nexus, and game data stored in DataScript. The interface is mostly a map of the United States; the player's controls are on the left side. In the original implemenation, each component had buttons which triggered a Replicant event when clicked, then Nexus routed the event to an action that produced an effect and updated the DB, often by setting a new UI component in the DB. Then the renderer would update the UI with the new component.

That's a fairly standard rendering loop for Replicant, but putting a UI component in the DB was an experiment. I didn't end up liking it. It made the game loop hard to follow through the code. I had to cross back and forth between code in two different files to trace the event fired by a component's button to the action handler that specified the next UI component, then find that component and its button(s). Even if all the logic had been in action handlers, the code would have been split into small pieces that required lots of jumping around in the file, goto style.

Also, using Nexus actions for the game loop made it hard to change the rules. The first version of the game gave the player a random hand of action cards to choose from, then chose a random action for the computer opponent, then gave the human player a totally new set of cards. That was good enough to get the basic mechanics working, but it didn't allow for any strategy across turns. I wanted to tinker with the game loop, but having the logic split between components and action handlers meant that changing the sequence of steps required rewriting the actions. That was tedious and error-prone.

To address both problems, I introduced a proper state machine. While I briefly toyed with a high-level, data-oriented definition of states and transitions, the need for a loop with a turn counter smelled like a programming language, so first I tried a different form of state machine: a core.async goroutine.

I hadn't used core.async in a while. Though I appreciate Go's model of communicating sequential processes, it's overkill for most of the helper scripts and small apps I write. In this case, I didn't need to execute code in parallel, but for something to serve as a goroutine's namesake, a pausable coroutine. After some refactoring, I ended up with a game loop defined like this:

(defn basic-game [conn turns]
  (let [chans [(async/chan) (async/chan)]]
    (async/go
      (let [[player1 player2] (<! (choose-party chans))]
        (<! (choose-hairdo chans @conn player1))
        (<! (choose-hairdo chans @conn player2))
        (loop [turns-left turns]
          (<! (set-turns-left chans turns-left))
          (if (pos? turns-left)
            (do
              (<! (choose-action chans @conn player1))
              (<! (choose-action chans @conn player2))
              (recur (dec turns-left)))
            (<! (results chans))))))
    chans))

The syntactic gynmastics of core.async chan, go, and <! make it a bit noisy, but it did centralize the logic of the game loop. The helper functions provided a domain-level grammar of the game's sequence.

The game initializes this goroutine during setup, stores the returned channels in the DB, sends Nexus effects keyed with :effect/send to the input channel, and spawns a second goroutine that listens for output messages and dispatches actions:

That requires each of the helper functions used by the goroutine to have some of the same syntactic overhead as the main loop, littered with go and <! and >!. Maybe that boilerplate could be cleaned up with macros. But a perfect DSL wasn't my main concern. I was more interested in having a game loop defined in a compact and comprehensible chunk, as well as one that could be easily swapped out for a different loop. A goroutine gave me that. I could fiddle with the loop so each player started with random cards then discarded played cards and kept the rest for the next turn:

(defn hand-of-actions [conn turns actions-per-turn]
  (let [chans [(async/chan) (async/chan)]
        hand-limit actions-per-turn]
    (async/go
      (let [[player1 player2] (<! (choose-party chans))]
        (<! (choose-hairdo chans @conn player1))
        (<! (choose-hairdo chans @conn player2))
        (loop [turns-left turns
               hand1 (db/random-actions @conn hand-limit)
               hand2 (db/random-actions @conn hand-limit)])
	      (<! (set-turns-left chans turns-left))
	      (if (pos? turns-left)
	        (let [[played1 hand1] (<! (choose-actions chans @conn player1 hand1))
	              [played2 hand2] (<! (choose-actions chans @conn player2 hand2))]
	          (recur (dec turns-left)
	                 (replace-action @conn hand1 hand-limit)
	                 (replace-action @conn hand2 hand-limit)))
	        (<! (results chans)))))
    chans))

I didn't have to add features to a custom state machine evaluator, but instead used Clojure's built-in language constructs to keep state between passes through the loop. A minimum viable implementation.

The end result is more complicated, with more moving parts—a game-loop goroutine running in the background, a goroutine listening for output messages, channels saved to the database—but it grouped logic according to its responsibilities and made the individual parts easier to reason about.

That's the important part. A functional language like Clojure usually avoids the kind of imperative logic above, but sometimes the clearest expression of a solution is step-by-step. Especially for a game, which is inherently imperative. Do this, then do that. The goal isn't to always avoid side effects and only use pure functions. My original Nexus handlers were pure functions. The goal is to make code understandable and to facilitate new ways of using it. Having clusters of tiny pure functions can undermine those goals.

Both the code and the game have plenty of room for improvement, but using a core.async goroutine allowed me to define different new game loops easily enough to arrive at some rules my son found fun to play, and hopefully one that taught him a little about the electoral college and geography (and wordplay).

If you have suggestions for the game, or the code, feel free to email me.

Originally I planned to walk through the various jobs I've held and compare them to higher and higher parts of the knowledge funnel, moving from junior-level "code" up to principal-level "mystery", but it struck even me as dry and not very helpful for guiding career decisions, so I pivoted to talk more about turning ambiguous ideas into concrete realities. To illustrate, I started with an activity. I paired up the kids and asked teams to design an app that would help people eat healthier. Remembering my own high school class, I expected they'd need elaboration or cajoling, but I was pleasantly surprised how readily they jumped into the task without further instruction. Digital natives, I guess.

After about five minutes each team described their idea. They were all different, though they had the same underlying goal. As a software engineer, my job is often to surface those kinds of differences in how stakeholders, designers, and devs imagine a product or interface.

When I was fresh out of college, I noticed how different the working world was from school. Rather than being given closed-ended problems and having to find the right answer, I was given open-ended problems which often required asking more questions. And there were no right answers. Instead, every choice had tradeoffs. My job is frequently to identify those tradeoffs and make either a recommendation or a decision.

I'm frequently an intermediary between parties, translating concepts and language between stakeholders, other developers, the computer, and (now) AI. Contrary to stereotypes of computer programmers, that role requires a lot of communication skills.

I concluded with some of my personal experiences:

I work remotely, and the students were old enough to remember COVID and doing school from home, so they had context for how WFH can be lonely but also less distracting. Personally, I prefer working from home. I can live almost anywhere (thanks now to Starlink), I'm paid much more than I was when I worked for a local software agency (thanks to having more employment options), and I get to spend way more time with my wife, kids, and the house and property that are my favorite place in the world.

I also explained some of the differences between big companies and smaller startups. Small organizations provide more opportunity to make an impact on the business, but huge FAANG corporations provide more opportunity to make an impact on the world. The compensation is different too. Startups sometimes offer equity to make up for less salary, but beyond a few famous examples, not many people get rich off startup equity, though it can occasionally provide a moderate windfall.

Job-hopping is common in the software industry. People often struggle to get promotions and raises without changing jobs every couple of years, but my experience is mixed. I've had jobs where I got raises and promotions, but also jobs where I didn't. My bigger gripe is having to change jobs to continue growing professionally, regardless of promotions or pay. It's very easy to get pigeon-holed. The better I've been at a job, the harder it's been for the business to replace me in a given role. Sometimes it's easier to jump into a new role at a new job than to convince your boss to take a gamble on your capabilities.

One student asked what "bad stories" I had. Overall my career has been reasonably positive, and I don't really have horror stories. Certainly there are experiences I didn't prefer at the time, but those experiences were also stepping stones to where I am now, which is a stepping stone to wherever I'll be in the future. I've had bosses I didn't like and coworkers who annoyed me, but the incidents were all fairly forgettable, and so far I'm free of tales about dropped production databases, unsecured S3 buckets, and expectations of working a 996 schedule.

In the first month, I typed very slowly and made lots of mistakes, all with the much higher cognitive burden of having to remember where a character was and which finger should press the key before I could type anything. A very frustrating month. In the second month, my fingers began to know where they needed to go, but by then I had developed the habit of thinking about each key before I hit it. Many times a finger found a character before I could remember where it was. At that point, I knew I could drop the mental load, and I spent the third month learning not to think about each key. After that, it just took some time to get back up to my old Qwerty speed.

I related that three-month learning curve to my grandfather not long afterward, and he thought it felt very similar to his experience learning Morse code in the Navy after he was drafted for World War II.

I don't know if I'm faster using Dvorak than I was with Qwerty. I don't have any data, but qualitatively I feel like I type about the same speed. What has changed is the amount of effort. At the end of a long day of typing, my hands were less tired using Dvorak than they were using Qwerty. When a coworker found out I used Dvorak, he exclaimed, "Oh, that's why your hands don't move when you type!"

Despite using Dvorak as my main keyboard for more than 15 years, I can still type Qwerty, though not as fast and I have to look at the keyboard as I type. I can't touch type Qwerty anymore. I knew a guy who used Dvorak when in Emacs and Qwerty everywhere else (or vice versa), and he had learned to switch between layouts fluently, but I never tried. The closest I've come is typing on an iPad, where I still use the default Qwerty layout. An iPad, of course, has no tactile feedback, so I have to look anyway, and I don't feel that I would be as fast looking at a Dvorak keyboard. It's as if my eyes know one layout and my fingers another.

The first time I saw this sight, I was riding across northern Indiana in the early morning hours, awoken by my wife as she drove. Neither of us knew what it was. The eeriness of it is the closest I've felt to a UFO encounter, but now, 15 years later, these sights are common. On that drive across Indiana, she woke me again near dawn to tell me what they were. Windmills.

The red lights, of course, are safety lights to warn planes, and recently while driving across Kansas in the dark and thinking how glad I was not to have this blinking array out my bedroom window, I supposed it could be important for the lights to all blink together. If each light blinked on its own schedule, it would create a continuous scintillation, which could be even more disruptive:

So I have some questions:

1. Is it a safety consideration for the lights to blink together, or aesthetic?
2. Is synchronized blinking required when building a wind farm?
3. What's the mechanism for synchronizing the lights?

If you know any of the answers, I'd be happy to hear from you.

In this particular case, I introduced a new vertical slice of functionality, which required adding a lot of new classes. I became curious how many classes had to be added, how many methods, and how many imports, to have a better idea how much similar work might be required for future vertical slices. I tried going through the changes and counting, but the counts were difficult to track. Instead, I added comments to the diff.

The unified diff format output by Git doesn't natively support comments, but since I wasn't using the diff afterward, it didn't matter. I used # in the first column to denote a comment, then added comments for any changes of interest, such as class added, method changed, import added, external interface changed, unit test added, etc. Afterward, it was simple to tally the changes with a Bash command:

cat annotated-changes.diff | grep '^#' | sort | uniq -c | sort -nk1r

That finds all the comment lines, sorts them, counts unique lines, then sorts by count, with the most common changes listed first. With those results, I got a quick bird's-eye view of the vertical slice. It took some manual tagging within the diff, but I didn't want to write even a rudimentary parser for a one-off task I could do the hard way in a few minutes. And that annotated diff may be useful in the future, such as if a stakeholder asks why there's so much friction for a new feature, I can provide specifics on how a dozen new classes were needed (for transporting data between different layers) and how three times as many imports were needed to make those classes available in the expected places.

If you have other suggestions for using diff files as part of your workflow, please email me.

In my oversized branch, I write the full diff to a file with something like git diff main... > changes.diff. Then I review the changes, looking for what parts are trivial cleanup that could go in a separate branch and be merged without any of the other work I've done. I copy those files out into a new file, say, cleanup.diff, remove irrelevant chunks, and delete from changes.diff the chunks that got copied. Sometimes chunks themselves need to be edited, which can be tricky, since Git's diffs include information about what line changes start at and how many lines were changed, information that has to be updated if I add or remove lines from a chunk.

Once I've pulled out all the simple cleanup changes, I look for refactors. Those chunks go in another file, e.g. refactor.diff. Sometimes an oversized branch has multiple refactors, and multiple diff files are needed to untangle them into separate threads. When I'm done, the chunks remaining in changes.diff should reflect functional changes.

Once I have all the diff files, I figure out how to structure my pull requests. I create a new branch for the first set of changes, run cat something.diff | patch -p1, test, and if all is well, open a PR. After that, I create a new branch off the first branch and apply the next diff. It may or may not work. Sometimes the subsequent diff files don't align perfectly with a subset of the original changes, but even if the diff applies cleanly, the code might not function correctly, because often changes are tough to eyeball from a diff. Tweaking is frequently necessary. Once I've tested and gotten the second branch working, I continue on through any other diffs I have, branching from the appropriate base branches. Usually only two branches are necessary; in extreme cases, three. Any more than that and I tend to break out cleanups and refactors before finishing exploratory work, so that exploration is clearer and without as many distractions.

Whether I create PRs for each branch immediately depends on team culture. For some teams, I've only created branches one at a time, keeping others in reserve until the PRs they depend on get merged. That simplifies the mental landscape for reviewers, since PRs targeting other PRs can be hard to reason about, but it can also be simpler for me as the code author. When reviewers have feedback, I can make changes to the branch and rebase downstream branches without worrying that others have already pulled those branches. If I do open subsequent PRs before the first one is merged, I target the open branch and note in the PR description that it depends on another PR, then I rely on GitHub to automatically retarget a PR at the main development branch when its base branch is merged.