Field Notes

Language Design

2024-04-02T00:00:00Z

The hardest part of programming language design is what you leave out. Every feature is forever; every feature interacts with every other feature; every feature is a thing the implementer has to maintain and the reader has to learn.

The orthogonality test

Two features are orthogonal if they can be combined without surprise. If feature X breaks when used inside feature Y, the language has a wart that grows over time.

Most language warts come from features designed in isolation: pattern matching that doesn’t compose with lambdas, generics that don’t compose with subtyping, async/await that doesn’t compose with iterators. The fix is to design every feature against every other feature up front, before either ships.

Static vs dynamic

A pet division. Static typing pays a cost in expressiveness at the boundary (where types meet user-supplied data) and earns interest in the middle (where types meet other types). Dynamic typing pays its bill in inverse. Pick based on where the program spends most of its time. See Distributed Systems for an unrelated note about another classic trade-off.

Consistency Models

2024-03-12T00:00:00Z

A consistency model is a contract between a distributed system and its clients about what reads are allowed to see after writes happen.

The big three

Linearizable — every operation appears to take effect at a single instant between its invocation and its response. Hardest to provide; easiest to reason about.
Sequential — operations from all clients appear in some single total order, but the order doesn’t have to match real time.
Eventual — reads can see stale data; given enough time without writes, all replicas converge.

CAP theorem

Eric Brewer’s CAP theorem says: in the face of a network partition, a system must choose between consistency and availability. There is no third option.

This is why most production systems are tunable: they offer linearizable reads with a latency cost, or fast eventually-consistent reads, and the client picks per request.

See Distributed Systems for the broader context.

Distributed Systems

2024-03-08T00:00:00Z

The fundamental problem of distributed computing: you have many machines, each of which fails independently, and you need them to agree on something.

Eight fallacies

Peter Deutsch’s classic list of things you must never assume about a distributed system:

The network is reliable.
Latency is zero.
Bandwidth is infinite.
The network is secure.
Topology doesn’t change.
There is one administrator.
Transport cost is zero.
The network is homogeneous.

Every distributed-systems failure mode is a corollary of violating one of these. See Consistency Models for the most important consequence: you can’t have everything.

Consensus

The canonical problem is consensus: all nodes agree on a value despite some subset failing. Paxos and Raft are the standard solutions. The cost is a network round trip per decision.

The Zettelkasten note (Zettelkasten) is unrelated content-wise, but the shape is the same — a graph of nodes that must converge by exchanging messages.

Backlinks

2024-02-12T00:00:00Z

A backlink is a link pointing to a note, not from it. Tracking them turns a wiki from a directed tree into an undirected graph: you can follow the conversation in both directions.

Construction

A backlinks index is just an inverted-index pass over the corpus. For every page, walk the rendered AST, collect every internal link destination, and append the source page to the destination’s bucket.

The juicer engine does this during the markdown pass and exposes the result as .page.backlinks — a thin list of {title, url, summary} records, sorted by referrer title for deterministic output.

Tools like Roam, Obsidian, and Logseq made backlinks a first-class UI affordance; juicer just bakes the same idea into a static site generator. The implementation here is the same shape as Zettelkasten, just done at build time instead of at edit time.

Edge cases

The collector filters:

Absolute URLs (https://…, mailto:, tel:)
Fragment-only anchors (#section)
Self-links
Query strings and fragments are stripped before matching, so [X](/target/#section) and [X](/target/?q=1) both count as a link to /target/.

See Distributed Systems for an aside on graph algorithms generally.

Atomic Notes

2024-02-11T00:00:00Z

An atomic note is a note that holds exactly one idea, expressible in a few paragraphs at most. The atom is the smallest unit that can be reused intact in another context.

The discipline of writing atomic notes is what gives a wiki long-term legs. See Zettelkasten for the historical method that put this idea on the map.

Cues for splitting

If you can write a new title for a section of a note that doesn’t repeat the parent title, the section probably wants to be its own note. Linking is cheaper than scrolling — and the inbound link will surface in the parent’s backlinks panel automatically.

Cues against splitting

Don’t split for the sake of splitting. A two-paragraph note with no neighbours is information, but a two-paragraph note that’s part of a network of five is knowledge. Aim for the latter; let the former hibernate until something else points to it.

See also Backlinks for the mechanism that makes the network legible.

Zettelkasten

2024-02-10T00:00:00Z

The Zettelkasten (“slip box” in German) is a personal knowledge management method developed by sociologist Niklas Luhmann. The core idea: each note holds one atomic thought, identified by a unique number, and notes link to each other to form a network of ideas rather than a tree.

Why atomic notes

A note that does one thing can be reused in many contexts. A note that tries to be a chapter can only be one chapter.

When a note grows past a few paragraphs, it usually wants to be split. The cue is often that you can write a new title that doesn’t repeat the old one — which is the cue that you’ve drifted into a new topic.

Linking

The link is the unit of structure. There’s no folder tree. The wiki is just notes plus their links. See Distributed Systems for an unrelated example of the same “everything is a network of nodes” idea.

Backlinks

A note shows you who links to it, not just who it links to. That inversion is what makes the wiki feel like a network and not a tree. See Backlinks for the implementation notes.

About

2024-01-01T00:00:00Z

This wiki is built with juicer using the juicerwiki theme. Notes live as flat markdown files under content/; every internal link automatically populates the linked note’s backlinks panel.

The closest cousin of this layout is the original Zettelkasten method as practiced by Niklas Luhmann. The original was a paper card index; this is the digital equivalent without the index cards.