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.

For a long time I would revert the whole branch without committing, then stage reverted chunks one at a time, clear the unstaged changes, and check for the bug or test failure. That worked alright, but it could often get confusing. It can be a little tricky to think in terms of staging reversions, and if the set of changes didn't fix the problem, or introduced a new problem, such as by not undoing some related changes, then I had to reset my git index and start over. Now I stage changes via diff files, instead of using Git's staging area. Here's how.

I start on a branch off the main development branch (main), then clear the working directory of uncommitted changes, either by committing them, stashing them, or discarding them. Then I create a reverse diff and save it to a file with git diff main... -R > changes.diff. That diff captures the changes that will undo the entire branch and make it identical to main. Since I only want to undo specific changes, I open a new file, say, candidate.diff, and copy sections of changes.diff over to it one at a time. Diff files are arranged as chunks within files, so it's easiest to copy across the full file then delete any unwanted chunks. Once I have the changes I want undone in candidate.diff, I apply it with cat candidate.diff | patch -p1, then check for the bug or test failure. If the problem isn't fixed, or if some additional reversions are needed, I try again by clearing changes with git checkout -- ., then I edit candidate.diff, run the new patch, and test again.

I've been using much smaller, more atomic commits lately, so git bisect works well, and it's been a while since I needed this workflow. Next time I do need it, though, I plan to write some helper scripts. For example, here's a small script to alleviate the confusion of patching reversions by first reverting the whole branch, then applying the positive diff:

#!/bin/bash

patch=$1

git diff main... -R | patch -p1
cat $patch | patch -p1

If you have other tips for troubleshooting changes on a Git branch, email me.

I briefly considered building my own web UI. I did that a few years ago when working on a team that hosted their code on BitBucket after I'd gotten used to GitHub reviews and treating review comments as notes to myself, coming back to delete questions answered by later code or clarifing thoughts before publishing anything. But before diving into a frontend application, I took a lesson from drafting pull requests locally and decided to see how far I could get with a diff, NeoVim, and some scripts.

A big advantage of reviewing code in a local text editor is that it can handle large diffs without requiring me to click "Load diff" on particular files or only showing one file at a time, which allows searching the whole set of changes for particular patterns, such as TODO comments or the catching of too broad exceptions. I can also exclude files in bulk, like generated code, documentation, and tests, depending on what my focus is for a given review. It's also a lot easier to review changes made since the last review, just by creating a diff with git diff <last-reviewed-commit>...HEAD.

But it's not a perfect experience, and I did a lot of customization to NeoVim to make it more diff-friendly. For starters, GitHub allows collapsing files. To support collapsing both files and chunks within a file, I defined a fold method and expression:

setlocal foldmethod=expr
setlocal foldexpr=v:lua.diff_fold_level()
setlocal foldtext=v:lua.diff_fold_text()
setlocal foldlevel=99

The Lua functions are implemented in Fennel:

(fn file-start? [line]
 (string.match line "^diff")

(fn chunk-start? [line]
  (string.match line "^@@"))

(fn _G.diff_fold_level [line]
  (let [line (vim.fn.getline (or line vim.v.lnum))]
    (if
      (file-start? line) :>1
      (chunk-start? line) :>2
      :=)))

(fn _G.diff_fold_text []
  (let [line (vim.fn.getline vim.v.foldstart)
        count (+ 1 (- vim.v.foldend vim.v.foldstart))
        level (_G.diff_fold_level vim.v.foldstart)
        prefix (case level
                 (where :>1) ""
                 (where :>2) "▶ "
                 _  "")]
    (.. prefix line " (" count " lines)")))

It's often helpful to jump from the diff to a particular file, to see the full context of the current code, so here's a command that uses the cursor's current position to find the right file name and chunk header, then calculate where to go and open it in a new tab.

Some chunks are not interesting and can be deleted from the diff, or whole files. Sometimes part of a chunk can be deleted but not others, so I also have a command to delete from the top of the chunk down to the cursor, which also updates the chunk header so jumping to the chunk's position in the file still works.

Often I start a review with the smallest changes, so here's a Babashka script that sorts the files in a diff by how many lines each file has. Using it for a while, I've added the ability to sort by how many additions each file has, or deletions, or how close the ratio of additions to deletions is, or whether the file name contains the word "test". And here's a script that moves the first file to the end of the diff, for cases where I don't want to delete the file but also don't want to review it yet.

Beyond shuffling code, I also needed to add comments. I opted to use markers in the first column of the dif, adding v and ^ to indicate what range of lines I'm commenting on, and x to indicate the end of a comment, like this:

diff --git a/old_file.txt b/new_file.txt
index 2a2e9f1..a48d7f5 100644
--- a/old_file.txt
+++ b/new_file.txt
@@ -1,1 +1,2 @@
-Notes on changes
+An ode
v
+To my code
^
👏
x

I add those markers with a couple of NeoVim commands that also put the highlighted lines into the copy register, which allows using them in an UltiSnips expansion, such as for making a suggestion. It's also trivial to adjust the range of lines being commented on by moving the markers, while to adjust the range of a comment on GitHub I have to copy a comment's content, delete the comment, select a new range, create a new comment, and paste the original comment.

I have a script to collect those comments as Markdown, with file and line metadata in the header of the fenced code block:

```diff new_file.txt -2 +2
+To my code
```

👏

Comments are separated by ---.

I write those comments to a file, tweak them if necessary, and create a pending GitHub review with this code. I keep that file of comments as a place to track what comments have been addressed and how, whether a requested change was made (and in what commit) or an answer was given for a question.

One final advantage of using NeoVim is how easy it is to define key bindings for all these actions, especially repeated actions using vim-repeat, making code review very fluid.

There are, however, some pitfalls. One is that it's easy to delete chunks that have comments. To avoid losing work, I added NeoVim functions that write any deleted or truncated code that have comments into a separate file, which I later use to create the Markdown comments. Another problem is that I don't see anyone else's comments while reviewing, so I occasionally make duplicate comments or miss explanations that aren't in the code. The most annoying pitfall, though, is not having the latest revision locally, causingy my comments to end up on the wrong lines of the current revision. That's part of the reason the script which creates the review only creates a pending review, so I can check it before submitting (though finding pending comments in GitHub's review UI is still a challenge).

I volunteered to review these large PRs because I'm always curious where my personal workflow hits a breaking point, and finding the friction gives me an opportunity to improve my tools in ways that benefit small tasks too. If you have further suggestions, or ideas on how to mitigate the pitfalls, email me!

The buttons on the right add shapes to the both grids, the upper grid showing the shape in Euclidean geometry, while the lower uses the Manhattan distance to draw the shape in taxicab geometry. The same control points are used for both plots. Drag points to change the shapes. To reset the plots, click the "Clear" button. To export a plot as an SVG, click "Export SVG" on the upper right of each plot.

The current implementation defines each shape as a two-dimensional signed distance function, where negative values denote the inside of a shape, positive values the outside, and zero values the boundary. To draw the boundary, it uses a simple marching squares algorithm. It's not particularly fast, especially not at the level of recursion needed for a smooth curve. Thus, when dragging points, you'll see the recursion level drop and shapes become less precise, which helps keep the visual responsive, though it's by no means as fast as one would hope.

Nor is the algorithm flawless. The boundary will occasionally spill into a square whose corners are all outside the shape, so the boundary inside that square is missing. It also misses cases where the boundary itself becomes two-dimensional, as it can for midsets and difference-based hyperbolas. But speed wasn't necessary for the few static illustrations I needed, and unhandled edge cases were easy to avoid.

I played with partial support for additional Minkowski distances, but while the shapes were interesting, their meaning was much harder to intuit, and broken edge cases were more common.

The original prototype, with all the same functionality, was about 500 lines of ClojureScript code. The public playground is slightly shorter, thanks to offloading some functions I commonly use to a library.

If you have suggestions for improvements, I'm happy to hear them.

These shapes are cousins of the ovals of Cassini, which are a constant product of distances to two foci. Here, though, one of the foci is a line, so half the shape wraps a focus that extends to infinity:

Similarly for taxicab geometry:

Both can be fully disconnected:

or fully joined:

Interesting things happen to the taxicab shape when the directrix is neither horizontal or vertical. Here it is at 45° to the axes:

With a sloped directrix, the shape becomes asymmetric (and, to my imagination, birdlike):

In Euclidean geometry, these appear to be a parabola:

That makes sense, since a parabola is the set of points equidistant from a focus and a directrix, or having zero difference in distances.

Interestingly, though, this definition can also produce a kind of double parabola:

Taxicab geometry has analogs for both:

The double parabola above just looks like two angled lines, and to see them as overlapping parabloas requires some foreknowledge of what you're looking for.

With the directrix at 45° to the axes, the shape still looks like a taxicab parabola with a similarly sloped directrix:

When forming a double parabola against a directrix at 45°, the shape becomes two right angles:

With a sloped line, some foreknowledge again helps to see the underlying pair of overlapping parabolas: