PatLang: A Primer, Read as a Crime Scene

ReadRead this before whichever "Journey" instalment you've been given. It uses the same forensic and anatomical vocabulary as the lecture-series pages on this site — if you haven't read those yet, the short version of each idea is below, so you don't need to.

The premise

TwoTwo of this site's own lecture pages argue that debugging isn't really a maths problem — it's an investigation. "The Criminology of Code" treats a bug the way a detective treats a crime scene: preserve the evidence, establish motive, trace the method. "Software Engineering as Systemic Anatomy & Pathology" treats a running system as a living organism rather than a diagram: it has organs with distinct jobs, and when one organ fails, the pain is often felt somewhere else entirely.

The "Journey of Building PatLang" series is, from start to finish, one long, real transcript of exactly this kind of investigation, happening for real, over more than a year, on a real project. Nobody wrote it to illustrate the two lecture pages — it just turns out to be full of near-perfect examples of both, because that's what real debugging actually looks like. This primer reads the series through that lens on purpose.

Vocabulary from "The Criminology of Code"

• Preserving the scene. A real investigator's first rule: don't disturb the evidence before it's recorded. In code, that means capturing a reliable, reproducible failing test — Kent Beck's "chalk contour" — before touching anything, even code you're sure is unrelated. Fixing the first plausible-looking thing you spot, before you've actually secured the scene, is one of the most common ways an investigation goes wrong before it starts.
• Motive and intent. Old, strange-looking code often made perfect sense given constraints that no longer exist. git blame, commit messages, and comments are the closest thing software has to a suspect's own statement, made before they had reason to reconsider it. Reconstructing why something was written is usually harder than understanding what it does.
• Modus operandi — the signature of a bug class. Different kinds of bugs leave different, recognisable traces: a memory leak leaves a graph that only ever climbs; a race condition leaves failures that correlate with load, not with any one input; a state-mutation bug leaves a value that's fine going in and wrong coming out, with no obviously guilty line in between. Learning to recognise the signature is faster than re-deriving the failure mode from first principles every time.
• Hotspots and temporal coupling. Adam Tornhill's Your Code as a Crime Scene — the book this whole lecture is named after — mines a project's commit history the way a real investigator profiles an offender's territory: files that change often and are complex are the codebase's likely "repeat offenders." Files that keep changing together, even if nobody remembers they're related, are "temporally coupled" — a data-driven replacement for a developer's own unreliable memory of what's entangled with what.

Vocabulary from "Systemic Anatomy & Pathology"

• The anatomy. A system has organs with different jobs: a skeleton (interfaces and boundaries, holding shape), a cortex (the actual decision-making logic), limbs and actuators (I/O, database writes, network calls — where the system touches the messy real world), an immune system (validation, type checks, assertions — rejecting malformed input before it reaches anything important), and an autonomic system (garbage collection, thread pools, background housekeeping — runs silently, and when it fails, it doesn't crash the "mind," it degrades everything slowly and confusingly).
• The pain is often felt far from the cause. Charles Perrow's "normal accidents" and Nancy Leveson's systems-safety work make the same point from two directions: in a complex system, a failure is very often not one broken part, but two correctly-functioning parts interacting in a way nobody designed for. "Which component is broken?" is frequently the wrong first question. "Which two working components are now fighting each other?" is often the right one.
• Decay is normal, and it's a disease you manage, not an event. Lehman's laws of software evolution say a maintained system will still drift toward disorder unless someone actively fights it. This isn't a moral failing — it's closer to an organism ageing, and it's detectable early if someone's actually watching for it.
• Surgical refactoring. Changing a living system without killing it means operating on one structure at a time, keeping vital functions running throughout, and verifying the patient is still alive before you close up — never one big irreversible cut. The "strangler fig" pattern (routing more and more real traffic to a new implementation while the old one keeps working) is the direct engineering version of a staged operation rather than a transplant done in one go.

Where PatLang plays out almost every one of these, on the record

YouYou don't have to take the metaphor on faith — the Journey series contains close-to-literal versions of nearly all of the above, usually more than once. A few to watch for, wherever you're reading:

• A misdiagnosed crime scene. In one Act, a parser reports a bug at a specific line in a specific file — accurate as far as it goes, but about entirely the wrong file, because of a hidden preprocessing step nobody had accounted for. Two full rounds of investigation went into treating the wrong suspect as the right one before an independent check caught it. This is "establishing motive" gone wrong: trusting the confession without checking the alibi.
• A recognisable modus operandi, reused by the same offender. The single most-repeated bug across the whole series is the same one, in disguise, over and over: a variable read that silently copies an entire list or string, turning something that should be fast into something that gets catastrophically slower as inputs grow. Once you've seen its signature once — code that's mysteriously fine on small inputs and falls off a cliff on large ones — you start recognising it on sight, exactly the way the lecture argues an experienced investigator recognises a familiar MO.
• An immune system with an autoimmune disorder. One safety check exists specifically to stop a plain number being mistaken for a genuine memory address — a real "antibody" rejecting something that looks foreign. Except it was written to only accept addresses from one specific region of memory, so it started rejecting something completely legitimate (ordinary text written directly into the compiled program) as if it were the intruder. The immune system was attacking healthy tissue.
• The autonomic system quietly overloading the whole organism. A background search process, left running, quietly consumed 35 gigabytes of memory across several forgotten copies of itself and brought the whole machine down — the software equivalent of an "autonomic" process (something running silently in the background, not part of any deliberate decision) taking the entire body down with it, with no single dramatic moment where anyone chose for that to happen.
• Blaming the wrong organ. A recurring type-classification bug survived four separate serious attempts to fix it, every one of them aimed at the classifier itself — the equivalent of repeatedly operating on an organ that was never actually diseased. The real fault was a single missing line in a completely different, much simpler function one layer away. "Which component is broken" was the wrong question for a long time.
• Genuine surgical refactoring, on the record. The project's move away from external assembler and linker tools happened behind a feature switch, left off by default, tested hard before ever being flipped on for real work — a real strangler-fig operation rather than a single irreversible cut, with the old system still available the whole time in case something went wrong.

How to use this while reading

AsAs you go through whichever Act(s) you've been assigned, try tagging each bug with one question from each lecture before you read the "lesson" the page states explicitly:

1. Forensics: was the scene preserved before anyone started poking at it — and whose "motive" (an old design decision, a since-removed constraint) turned out to explain the bug?
2. Anatomy: which organ actually failed — and did the pain show up in that same organ, or somewhere else in the system entirely?

If your own answer disagrees with the page's own conclusion, that's worth noticing. Being wrong about which organ is diseased, or which suspect had the motive, is exactly the failure mode both lecture pages are trying to train you out of — and it happens to the actual developer running this real project, repeatedly, on the record. That's not a reason to feel bad about getting it wrong yourself. It's the whole reason this is good material to practise on.