PatLang: A Primer Before You Read the Journey Series
Read this first — it's short, and it'll save you being confused for the first two pages of whichever instalment you're assigned.
Why you're being asked to read a language's commit history
Your lecturer has pointed you at "The Journey of Building PatLang" — a long, chronological diary of a real programming language being built, written directly from its own commit messages. It is not a textbook example. Nobody cleaned it up afterwards to make the author look good. It includes the wrong turns, the bugs that took hours to find, and the moments the author was confidently wrong and got corrected.
That's the point. Most of what you'll read about software engineering presents finished, tidy knowledge: here is TDD, here is a design pattern, here is how to test properly. This series shows what it actually looks like while it's happening — including the part where "100% of our tests pass" turned out to mean something different from "the code is correct." You will get far more out of reading it as a detective story than as a reference manual: someone hits a problem, chases it down several wrong paths, and eventually finds the real cause. Try to guess the cause yourself before you get to the reveal.
You don't need to know PatLang's actual syntax to follow any of this. Every page is written to be readable by someone who's never seen the language — including you.
A few terms you'll keep running into
- Self-hosting / "the fixpoint" — PatLang's own compiler is written in PatLang. "The fixpoint" is the moment that becomes provable: the compiler compiles a fresh copy of its own source code, and that fresh copy behaves identically to the original. It's the programming-language equivalent of a snake successfully eating its own tail and surviving.
- Three execution paths — PatLang programs can be run three different ways: interpreted (read and run directly, like Python), natively compiled (turned into a real .exe), and self-hosted-compiled (compiled by a compiler that was itself compiled by PatLang). The project's rule is that all three must give byte-for-byte identical results before a feature counts as finished. A lot of the interesting bugs in this series only exist because someone insisted on checking all three, instead of stopping once one of them worked.
- Mirror drift — what happens when the same logic is written out twice (say, once in the main compiler and once in a self-hosted copy of it) and a fix only gets applied to one copy. It sounds like an obviously avoidable mistake. It happens constantly in this series, to an experienced developer, on a project they know intimately — which is exactly why it's worth paying attention to.
- GOAP (Goal-Oriented Action Planning) — instead of hand-scripting every possible thing a character (or, here, a piece of code) might do, you give it a goal and a list of available actions, each with a cost and a precondition, and let a search algorithm work out a plan. Borrowed from game AI — see the Games track if you want the concept from scratch, with a worked example.
- The induction/synthesis engine — a system, built inside PatLang, that tries to write PatLang code by itself, given only example inputs and outputs (in a Given/When/Then format). Several of the best "wait, that's not actually proof of anything" moments in the series come from testing this engine.
- No try/catch — PatLang has no exception-handling mechanism at all. If you're used to
try/exceptortry/catch, notice how many workarounds this forces (writing state to disk so it survives a crash, checking return values obsessively) — it's a genuinely different way of having to think about failure. - Value semantics — by default, PatLang copies things when you read them rather than sharing a reference. Several times across this series, an operation that looked cheap was secretly copying an entire list or string on every single access, turning something that should take linear time into something that takes quadratic time — invisible on small inputs, catastrophic on large ones. Once you've spotted this bug once, you'll start recognising the shape of it everywhere.
How to actually read one of these pages
Each numbered "Act" follows roughly the same pattern:
Something is tried or reported → an investigation follows, usually with at least one wrong guess → the real cause turns out to be something specific → it gets fixed → the fix is checked, sometimes revealing it wasn't quite enough → a lesson gets written down in bold at the end.
Do this: when you hit the wrong guess, stop and predict what the real answer will turn out to be. You'll be wrong a good chunk of the time, and that's useful — it tells you something about your own assumptions.
The pages also quote the actual developer running the project verbatim, in italics. Pay attention to these. Some of the sharpest lessons in the whole series come from that person catching a mistake, pushing back on a lazy assumption, or correcting something stated too confidently — for example, one whole page turns on the developer noticing "looks rather open for something that's been closed…" and being right. Reading how a good technical collaborator gives feedback is its own useful skill, separate from the coding lessons.
Which page am I actually looking for?
If you've been pointed at a specific instalment, this is roughly what each one is about:
| # | Title | What's actually in it |
|---|---|---|
| 1 | The Journey of Building PatLang | How the whole project started; the "100% tests passing" trap; a brief AI-agents-writing-code experiment |
| 2 | Teaching It to Write Itself | Building a system that writes its own code from examples; why testing on toy data isn't enough |
| 3 | Hardening What Already Worked | A bug that was blamed on the wrong file; putting PatLang inside someone else's app; a long performance chase |
| 4 | Real Inheritance, at Last | Adding classes/inheritance/traits properly — planned in writing before any code was touched |
| 5 | Teaching It to Find Its Own Answers, for Real | Testing an AI-search system honestly, including three times it looked right and wasn't |
| 6 | Taking the Native Backend Seriously | Wrong-answer bugs that don't crash (the dangerous kind); a case where the "obviously correct" engineering advice was actually wrong |
| 7 | The Fixes That Weren't | Bugs that had already been "fixed" once, except the fix never actually took effect |
| 8 | Giving It a Window | Making PatLang open a real on-screen window; new bugs that only show up once real multi-threading exists |
| 9 | Searching Backward | A search algorithm gets smarter, and an honest account of a fix attempt that made things worse |
| 10 | Retiring the Last External Dependency | Two independent tools disagreeing with each other, and how to actually find out which one is wrong |
Each page ends with a short bulleted "Lessons from this arc" section — if you're short on time, read that first and then go back for the story behind whichever bullet actually interests you.
What to get out of this, practically
If you take one habit away from this series for your own project work, make it this: notice the difference between "this passed" and "this proves what I think it proves." Almost every recurring failure in this whole history is a version of that gap — a test passing for the wrong reason, a benchmark measuring something other than what it looked like it measured, a claim believed because it sounded plausible rather than because it was checked. That habit will serve you in your own coursework project long before you ever touch PatLang.