Blog Title

5 October 2025: Thoughts on Documentation vs. Self-Documenting Code

2025-10-03T00:00:00Z

A central problem with the idea of 'self-documenting code' is that natural human writing has a rhetorical structure designed to teach the reader basic vocabulary and concepts needed for understanding. Code -- especially DRY (don't repeat yourself) code -- is non-linear. As developers maintaining existing code, we're tasked with jumping into the middle and working backwards to understand what we need before moving on to the next ticket.

Let's say I get asked to rewrite the following bit of poetry to a different style:

Wailing her woe, the widow[1] old,
her hair upbound, for Beowulf's death
sung in her sorrow, and said full oft
she dreaded the doleful days to come,
deaths enow, and doom of battle,
and shame. -- The smoke by the sky was devoured.

Understanding this requires answering several questions.

Who is the widow? (Unstated in text, usually interpreted as Beowulf's widow.)
How did Beowulf die? (Killed by a dragon earlier in the same act.)
Who is he? Why does his death foreshadow doom and battle? (The loss of a community hero leaves it vulnerable to cycles of violence from neighboring groups.)

In poetry, these questions are answered organically over the course of three acts. In code, each entity might be separated into separate files or modules. Back-tracing the definition of each can be done through import declarations and LSP features, but this takes critical time. Understanding the lifecycle of each object can be another challenge.

In nonfiction there's a similar structure:

Introduction
Development
Argument
Conclusion

Each step teaches the reader the specific concepts, definitions, and meanings used within the work. By the time we get to the conclusions, most issues of ambiguity can be resolved.

Combining context and intent documentation with clear code can help make code easier to understand.

6 September 2025: More Nix with home manager

2025-09-06T00:00:00Z

Nixos after a week

So far so good. Been running a week and not experienced the issue I was having with wake from sleep. I didn't expect Nixos to become a daily driver, but it is for now.

Home-manager

One of my goals is to have a consistent set of software and utilities I can easily manage across multiple linux and Macos systems. These include:

helix and/or nvim: primary editors
fd and rg: "easier" replacements for find and grep
yazi, zellij, zoxide, chezmoi: shell helper utilities

Nix is very good at declaring software installs. And home manager built on nix seems like a good solution for keeping that list in my user-space.

Problem 1: Global or Standalone?

The home-manager manual has instructions for installing home-manager in stand-alone mode and as an extension of the global /etc/nixos/configuration.nix file. I found out the hard way I can't do both (documentation is inconsistent and a bit frustrating.) Standalone seems to be more portable. Integration with configuration.nix might be useful if you want to configure everything in one file.

The one change I made at the OS level was to add home-manager to environment.systemPackages in /etc/nixos/configuration.nix/.

Problem 2: Portability?

The recommend determinate MacOS installer uses the "experimental" feature flakes, which pushes me into flakes on Nixos as well. It took me a long time and a lot of fiddling to figure out how to use a flake as part of my home profile. I credit Zero to Nix for somewhat figuring out how flakes work, and Flakes aren't real and cannot hurt you: a guide to using Nix flakes the non-flake way for figuring out some perspective.

If you have flakes enabled as a feature, home-manager creates two boilerplate files, home.nix and flake.nix. However neither of these are exactly portable home.nix includes references to my username and home directory:

  home.username = "kaes";
  home.homeDirectory = "/home/kaes";

While flake.nix specifies a system architecture.

	system = "x86_64-linux";

Why not use environment variables? Nix with flakes considers environment variable, "impure", one of those pure-functional language choices that I understand but find annoying.

So far the hack I'm using is to add third file that only includes the list of packages I want installed. My packages.nix file is careful not to include any platform-specific code:

{ pkgs, ... }:

{
  home.packages = with pkgs; [
    btop
    fish
    fzf
    zsh
    helix

    gh
    nodejs_24
    typescript
    typescript-language-server

		...

    ripgrep
    fd
    neovim

  ];
}

This is imported into the boilerplate flake.nix as a module:

  outputs =
    { nixpkgs, home-manager, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in
    {
      homeConfigurations."kaes" = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;

        # Specify your home configuration modules here, for example,
        # the path to your home.nix.
        modules = [
          ./home.nix
          ./packages.nix
        ];

        # Optionally use extraSpecialArgs
        # to pass through arguments to home.nix
      };
    };

Ideally I want to either auto-detect the system and username or modularize that as a minimal local config. But I'm still a beginner at this.

31 August 2025: Surfshark and NixOS

2025-08-31T00:00:00Z

NixOS and Surfshark

With all the anti-trans news of this week I'm working on bringing up some better internet security, including a vpn subscription to Surfshark. Simultaneously, I'm distro-hopping again looking for a few improvements on some minor issues that individually are not a big deal, but over the months have become more and more frustrating.

NixOS is worth a shot. There are some configuration and software things I end up setting up in nearly every new computer. My experience at Amazon has sold me on configuration as code. And my personal laptop (Thinkpad E14 Intel Gen. 1) has some quirks that require some special handling. The NixOS config file reminds me of the Freebsd centralized config files. Nix has its own quirks.

Honestly the most challenging part so far was setting up Surfshark, which uses its own configuration client distributed as snap or flatpak. The first step was setting up flatpak according to wiki instructions.

  services.flatpak.enable = true;
  systemd.services.flatpak-repo = {
    wantedBy = [ "multi-user.target" ];
    path = [ pkgs.flatpak ];
    script = ''
      flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
    '';
  };

A trickier problem to fix was DNS resolution failures when Surfshark is active. A solution was to disable resolv.conf in favor of NetworkManager DNS settings. These settings configure the system to use the Surfshark DNS servers set through NetworkManager rather than attempt to use resolv.conf.

  services.resolved.enable = true;
  networking.resolvconf.enable = false;
  networking.networkmanager.dns = "systemd-resolved";

Future work:

using NixOS for a while to get a feel for how to manage it
separating agnostic command-line utils from linux-specific to possibly use nix on other systems

Kagi

Also experimenting with Kagi search. Never been comfortable with google's privacy models, their results just keep getting worse, and I like the ability to downrank less-reliable sites and sources that inexplicably get the top results elesewhere.

23 August 2025: React Reducer Pattern

2025-08-23T00:00:00Z

Some of my "side" project work includes prototyping with strategies that I'd like to apply at work. We have moderately complex, legacy Vue and React interfaces that are difficult to test for a variety of reasons. One of my maintenance tasks is look for ways to refactor for testability, and some of the themes for React are:

Division of application state into multiple useState() variables.
Internal React variables are not directly observable without rendering. This makes it difficult to test "business" (data modification) logic separate from UI rendering logic.
Multiple UI events can trigger state changes.
Tacit updates and component lifecycle events trigger unexpected results and errors.

The reducer pattern helps to address many of these problems.

ttrpg-tools is a side project to create a set of creative brainstorming oracles for solo role-playing games. Many of these games include a mechanic that increases the risk of negative events as play continues. Examples include jenga towers and playing card layouts.

My experimental mechanic uses solitaire blackjack with the addition of a "resource" pile of cards that can be played at any time. The "dealer" represents a hostile environment, and players will need to balance wins and losses to reach the endgame. My first attempt at managing game state through React's useState came out something of a mess, which pushed me to read more about useReducer as an alternative.


erDiagram

		direction LR
		state ||--|| view : configures
		state {
			Card[] playerHand
			Card[] dealerHand
			Card[] resources
			Card[] discardPile
			number playerScore
			number dealerScore
		}

		view ||--|{ actions : sends
		view {
			ul playerHand
			ul dealerHand
			ul resources
			div playerScore
			div dealerScore
			nav turnNav
		}

		actions }|--|| reducer : direct
		actions {
			action setupRound
			action playerTurn
			action playerHit
			action playerStand
			action dealerTurn
			action scoreRound
		}

		reducer ||--|| state : updates
		reducer {
			param state
			param action
			returns state
		}

Currently the game code consists of four main components, each with their own responsibilities:

The Game State: This is a class that manages the deck of cards, and multiple arrays representing a draw pile, player hand, dealer hand, and discard pile. It also contains functions for updating the total score, and calculating the score for each hand. This bundles almost all of the app state.
The View: A set of JSX components that is primarily responsible for displaying the current game state as a list of rendered cards and numbers. It also includes an action bar that displays only the actions relevant to each stage, and has minimal event handlers to create actions for the reducer.
Actions: Each action is a simple message object that represents a single game events a high level. These are sent to the reducer via a dispatch function. A simple action is:

{type: 'SETUP_ROUND'}

The Reducer: The reducer is a pure function (not triggering or depending on side effects) that takes the current game state and an action. It reads the action, calls the appropriate methods on the game state, and generates the next game state. It uses immer to ensure that the new state is an immutable copy.

The reducer is simply an extended switch statement. Here's a minimal example

/**
 * Create a reducer function using drawPile as the array iterator.
 * @param {ArrayIterator<Card>} drawPile
 * @returns {(SurvivalBlackjack, ReducerAction) => SurvivalBlackjack} reducer function
 */
export function makeReducer(
  drawPile: ArrayIterator<Card>, // shuffled deck for game
): (state: SurvivalBlackjack, action: ReducerAction) => SurvivalBlackjack {

	// The reducer starts here as a closure.
  return function reducer(state: SurvivalBlackjack, action: ReducerAction) {
    switch (action.type) {
      // start the game drawing resources
      case turnStage.start: // turnStage is a typescript enum
        return produce(state, (state) => { // immer.produce() ensures immutability
          state = state.setup(drawPile).setStage(turnStage.start);
        });
...

drawPile is an iterator object with its own internal state. I keep it separate from state to ensure that state can be immutably handled by both React and immer without complications. This is 'passed' into the reducer via a closure. The reducer and initial game state are created early and added to the view with the following line of code:

const [game, dispatch] = useReducer(reducer, initialGame);

This is parallel to [state, setState] = useState(initialState) State properties can be accessed through game.current for rendering. The view does not directly modify the state, which makes handling events very simple:

<button onClick={() => dispatch({ type: sb.turnStage.playerTurn })}>
  Start Game
</button>

dispatch calls the reducer, captures the new game state, and triggers a redraw. The reducer takes care of round and game management. The state methods take care of game mechanics. Some of the advantages include:

MVC organization.
Game management, game mechanics, and display logic can be tested independently.
Direct access to state properties for testing.
Game management and game mechanics are not dependent on any UI framework.
Interdependent states can be managed together, without worrying about the rendering cycle.

16 August 2025: Reviewing JS Functions

2025-08-16T00:00:00Z

Functions Review

I'm reviewing basic function and scope rules to help in working with some legacy code. I have my own style but I'm maintaining code that's written in a different style. See the Google Typescript Style Guide section on this for a suggestion to avoid using this and arguments.

Function Creation

Function Declaration is traditional. this is bound to parent object (Window in browser). Name is immediately available.

function add(a, b) {
	return a + b;
}

Function Expression: function defined but not directly declared with a name. Can only be used as an expression, typically assigned to something else. Similar to a lambda. this bound to context of invocation.

const add = function(a, b) {
	return a + b;
}

Arrow Functions: Concise lambda functions. No declared name. this bound to nearest ancestor at time of definition.

const add = (a, b) => a + b

Class Methods: Functions created as part of a class. this is bound to the created object.

class adder {
	add(a,b) {
		return a + b;
	}
}

Function Calling

The way functions are called can influence the behavior of the function by changing the context.

Function as function: add(1, 1) Standard way of calling functions. Returns return value. this comes from context parent.
Function as constructor: obj = new adder() Creates a new class instance. Implicitly returns new object unless return statement uses a different Object instance. this is new instance.
Function as object method: adder.add(1,1) Returns return value. this defaults to instance.
Function.prototype.bind(context) Creates a bound function in which this is bound to the specified context. Can also bind additional variables for currying.
Call and apply: add.call(context, a, b) and add.apply(context, [a, b]). Calls function with bound context and arguments.

Takeaways

Explicitly define context outside of instance methods.
Avoid ambiguity, avoid this outside of instance methods.
Use bind or closures when moving a function to a different context.

3 August 2025: Documentation Wishlist

2025-08-03T00:00:00Z

Documentation Wishlist

Most of these are things I had to reverse engineer refactoring a wizard component. And I'll probably forget all of this in six months when I'm asked to do a bugfix.

Module Level (README.md)

What are the UI frameworks and dependencies, and where can I find documentation?
What are the build requirements and process?
What are needed environment variables?

Linked Components (README.folder.md)

What is the goal or task?
Is there a component hierarchy? What is it?

Functions

Description: What is the business/ui purpose of this function?
Parameters
Return values
Error handling
Exceptions
Events
Side effects/state changes

August Goals

Get a deeper understanding of how JavaScript handles fundamental variables and functions.
Continue learning Czech.
Finish bell hooks, All About Love

20 July 2025: Home Music Server Setup

2025-07-20T00:00:00Z

Prepping for a move in October and working on digitizing old cds and setting up a backup server. Not creative work but productive.

Raspberry Pi 4 running Raspberry Pi OS. The Pi was left over from another project a few years ago. Setting it up for headless operation was pretty easy following instructions. Using an external HDD and an enclosure, also from an earlier project.
Basic Samba setup with a Music folder.
Navidrome music server.
Ripping: Asunder and Musicbrainz Picard for tagging/organization.

A goal is to move away from depending on streaming services to personal music curation. Some of the discoveries from the archives include some independently published local music by hometown bands like Salaam and a Live From Bloomington project I've not found on the internet. Also discovering CDs I didn't know we had, like three Beatles collections and a Siouxsie and the Banshees single.

I started a practice in spring of putting notable songs on a year playlist. It just crossed 100 songs:

Kae Sluder · 2025 Daily

13 July 2025: Vitest Mocking

2025-07-13T00:00:00Z

Some notes on vitest after working out a few things. Needed to look beyond the cookbook examples to why vitest and jest mocks work.

Modules are objects

Modules can be structured as objects with method variables. A simple module with one function (not complete):

// /src/mosaicUtils.ts
export const mosaicFetch = async (): Promise<string[]> => {
  const res = await fetch("/mosaic/index.json");
  const imageList: string[] = await res.json();
  return imageList;
};

Can be mocked as:

// App.test.ts
const exampleData = [
  "15th_century_egyptian_anatomy_of_horse.jpg",
  "163_of_'Five_Years_in_Siam_from_1891_to_1896_..._With_maps_and_illustrations_by_the_author'_(11249062174).jpg",
  "640px-Avon_Fantasy_Reader_8.jpg",
  ...
];

// Argument 1: source of the old module
vi.mock("../src/mosaicUtils", () => {
	// set up the mock function to return the data
  const mockMosaicFetch = vi.fn(async (): Promise<string[]> => exampleData);

  // return a new module
  return {
    mosaicFetch: mockMosaicFetch,
  };
});

`vi.mock()` and vitest "replace" the old module

The utility library is imported with:

import { mosaicFetch } from "../src/mosaicUtils";

vitest intercepts this import call and replaces the entire module, not just mosaicFetch.

Mocking one or some objects in a module

vi.mock() replaces the entire module, not just a single function. Use vi.importActual(sourceFile`) to include other objects without modification.

// from https://vitest.dev/api/vi.html#vi-importactual
vi.mock('./example.js', async () => {
  const originalModule = await vi.importActual('./example.js')

  return { ...originalModule, get: vi.fn() }
})

`vi.spyOn()` watches a single method, getter or setter

A spy can be used to watch a single function in a module with optional replacement. See documentation. The same mock can be made as:

import * as mosaicUtils from "../src/mosaicUtils";

vi.spyOn(mosaicUtils, "mosaicFetch").mockImplementation(
  async (): Promise<string[]> => exampleData,
);

Alternatively, spyOn can be used to count how many times the existing function is called during the test.

5 July 2025: Strudel, New Role, and Mermaid Diagrams in Eleventy

2025-07-05T00:00:00Z

Strudel: Learning to Understand cat, seq, and stack

I've been experimenting with music programming languages. This week it's been strudel which is built around the concept of a cycle—typically either a measure or a beat in most music notation.

Strudel interprets strings that represent sequences of notes, drumbeats, or other events. "c4 e4 g4" plays three notes of a c-major chord. But a tricky matter is determining how the notes should be interpreted. Does that fit in one cycle (fast) or three cycles (slow)? After a fair bit of frustration, I learned the following concepts for strudel. Something that tripped me up here was that the Strudel docs teach the abbreviated notation first.

cat ("<c4 e4 g4>"): treats each item in the list as a separate cycle. This can be used to create extended phrases or songs. This is also known as slowcat if you're using the long notation.
seq ("c4 e4 g4"): processes each item in the list inside one cycle. This is used to push notes inside a measure. (Also known as fastcat).
stack ("c4, e4, g4"): process each event in parallel and at the same time. Used for chords, but also having multiple instruments playing together.

Patterns can be nested inside each other. The example below is a simple Strauss waltz loop that consists of four sequences [bd rim rim] inside a cat <[bd rim rim] ...>.

Here's the logic in flowchart form.

flowchart TD
    Start["I want to play notes..."]
    Choice1{"... at the same time?"}
    Stack["stack"]
    Choice2{"... over multiple cycles?"}
    Cat["cat"]
    Seq["seq"]

    Start --> Choice1
    Choice1 -- Yes --> Stack
    Choice1 -- No --> Choice2
    Choice2 -- Yes --> Cat
    Choice2 -- No --> Seq

New Role

Starting in October I'll transition from contract to full time software development at Prime Revenue focused on JS. It's been a four-year journey and I'm very thankful for all the people at Ada Developer's Academy, Amazon, and Prime Revenue who have given me valuable support, advice, and learning opportunities.

Getting Mermaid on This Page

In the template base.njk, add the code to load and run the mermaid api.

<script type="module" eleventy:ignore>
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
</script>

Create a paired shortcode in eleventy.config.js to explicitly format the code block:

eleventyConfig.addPairedShortcode("mermaid", function (content) {
	return `<pre class="mermaid">${content}</pre>`;
});

Use the shortcode to wrap the mermaid code in a <pre> block in the post markdown.

{% mermaid %}
flowchart TD
    Start["I want to play notes..."]
    Choice1{"... at the same time?"}
    Stack["stack"]
    Choice2{"... over multiple cycles?"}
    Cat["cat"]
    Seq["seq"]

    Start --> Choice1
    Choice1 -- Yes --> Stack
    Choice1 -- No --> Choice2
    Choice2 -- Yes --> Cat
    Choice2 -- No --> Seq
{% endmermaid %}

28 June 2025: Shuffle and Backup

2025-06-28T00:00:00Z

Visual Card Shuffle

Continuing my exploration of cut-ups my sourcing interesting images from Wikimedia Commons and the Met Open Access collection. Then I shuffle the images and arrange nine of them on a grid:

Pain points:

Image manipulation in css: My original idea was to use css to zoom in on random sections of each image, hoping for some creative serendipity. After an evening struggling with this. I gave up and started curating square tiles manually. The result is a bit creatively more satisfying, and it's a nice easy low-bandwidth task.
Typescript: Kept getting warnings on a helper function that returns a JSX.Element type. Documentation on how to deal with it is inconsistent. Is it handled automatically by a vite setting (and if so, why is it being flagged)? Basic conclusion is that I need to learn a lot more about how to work with Typescript before picking it up for projects.

Next steps:

In-page documentation
A keep-and-draw mechanic with limited keeps

Backups

A few months ago the disk that had my only copy of multiple desktop backup failed. My thought process in procrastinating on new backups was:

Essential work is on github
Most of those backups were ephemera
I rarely re-read books
I've not looked at that stuff in a while
Well crap, my sewing patterns are gone.

The last point pushed me to set up backups on the Thinkpad T420 I mentioned earlier as a backup system. It was mostly easy sailing once I specified full paths and set up my ssh keys. I used the Pika front end for BackupBorg to make everything work.

Reading Quote

Taking responsibility does not mean that we deny the reality of institutional injustice. For example, racism, sexism, and homophobia all create barriers and concrete instances of discrimination. Simply taking responsibility does not mean we can prevent discriminatory acts from happening. But we can choose how we respond to acts of injustice. Taking responsibility means that in the face of barriers we still have the capacity to invent our lives, to shape our destinies in ways that maximize our well-being. Every day we practice this shape shifting to cope with realities we cannot easily change.

bell hooks, "All About Love," Chapter 4