docs(course): replace Scala bridges with general programming in 00–05, README, mentor, spec

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Lucas Winther
2026-10-29 01:57:10 +01:00
co-authored by Claude Opus 5.5
parent 9891bb596d
commit d8828e1b6a
11 changed files with 109 additions and 54 deletions
@@ -9,22 +9,28 @@ as *values* (an `IO` type and event streams) that the student builds from scratc
a single `run` call at the very edge of the program is the only place anything
actually happens.
**Why:** students who've had one Scala course know `map`/`filter`/`fold` and case
classes, but rarely know how to apply them to an interactive, stateful system. The
**Why:** students with general programming experience write interactive programs
with mutable state, loops and callbacks, and rarely know how to build one from
pure functions and immutable data. The
outcome we want is practical: by the end, a student can take a game written the
usual way (`snake.currentPos = ...`, `apple.pos = ...`) and convert it into a purely
functional system — and explain each step of how and why — because they have
actually done it, not just read about it.
*Change, requested 2026-10-29:* no Scala background is assumed any more; bridges now start from general programming knowledge.
## Audience
- Bachelor's/master's CS students with one prior Scala course.
- Bachelor's/master's CS students with general programming experience
(variables, loops, functions, classes/objects, collections, callbacks/event
handlers, unit tests, some OOP). No prior Scala or functional programming.
- Working **alone at home**. Two supported modes:
1. **Solo** — the text, tiered hints and tests carry them.
2. **With an AI as a Socratic mentor** — the course ships instructions that
make an AI assistant guide by questioning rather than handing over answers.
- Assumed: basic JS syntax familiarity is *not* required to be strong; Module 1
bridges from Scala.
introduces `map`/`filter`/`reduce`, immutability and functions as values from
scratch.
## Goals
@@ -83,9 +89,10 @@ actually done it, not just read about it.
once and language-neutral where possible; every code listing, signature and
exercise appears in all three languages (JS / Scala / F#) next to each other.
Where a concept is language-specific (Module 1, tagged unions in Module 2), the
module has a short per-track section. Bridges go from Scala (the shared
background) to each track — for F#, "the Scala thing you know is spelled like
this in F#".
module has a short per-track section. Bridges go from general programming
knowledge (loops, objects with setters, callbacks, the classic game loop, unit
tests and mocks, SQL, Git), in blockquotes labelled "From everyday
programming"; Scala and F# specifics are stated as track information.
- **Canonical data model, but designed first by the student.** *[call]* Module 2
has the student sketch their own model and answer design questions *before*
revealing the course's canonical model, which they then adopt and compare with
@@ -104,19 +111,19 @@ actually done it, not just read about it.
## Module sequence
Each module contains: concept text with Scala bridges, learning objectives,
Each module contains: concept text with everyday-programming bridges, learning objectives,
exercises with signatures in all three languages, tiered hints (nudge → stronger
hint → near-solution), Socratic discussion questions, test suites per track,
"further reading" links, and a short "in production" note (cats-effect, fs2,
Elm, Elmish, RxJS, etc.).
0. **Setup & how to use the course** — tracks, running tests, solo vs. mentor mode.
1. **Purity & immutability in JS for Scala people** — referential transparency,
`const` vs. immutable data, `Object.freeze`, spread copies, functions as values,
1. **Purity & immutability** — referential transparency, `map`/`filter`/`reduce`
instead of loops, `const` vs. immutable data, `Object.freeze`, spread copies, functions as values,
currying/composition (`pipe`, `compose`).
2. **The game as data** — `Point`, `Direction`, `Snake`, `GameState`; algebraic data
types as tagged unions in JS (mapping from Scala `enum`/case classes and F#
discriminated unions); smart constructors.
types as tagged unions in JS (and as Scala `enum`/case classes and F#
discriminated unions), `Option`, pattern matching; smart constructors.
3. **Pure game rules** — `step : State → State`: movement, growth, wall/self
collision, illegal 180° turns, eating.
4. **Randomness without side effects** — seeded PRNG as `seed → [value, seed]`;