Skip to content

Fix concept-continuity slips in chapter prose#34

Merged
mre merged 2 commits into
mainfrom
review/concept-continuity
Jun 21, 2026
Merged

Fix concept-continuity slips in chapter prose#34
mre merged 2 commits into
mainfrom
review/concept-continuity

Conversation

@mre

@mre mre commented Jun 21, 2026

Copy link
Copy Markdown
Member

What

A step-by-step continuity pass over the course, checking two things per chapter:

  1. No concept is used before it's introduced (even briefly). Deliberate, clearly-labeled forward/back references are fine; the course teaches ownership as a spiral on purpose. This pass only touches cases where something is used cold, or a reference points the wrong way.
  2. Every sentence is correctly placed (no dangling references to things that don't exist).

Chapters 00-02 were reviewed in detail by hand; 03-25 were inventoried (concepts introduced vs. used) and reconciled against the running ledger, then each flagged spot was verified before editing.

Changes (all prose / doc-comments, no behavior change)

Chapter Issue Fix
01 strings # Your first function — but the reader implemented three functions in the integers chapter Retitle to # A welcome message
04 functions 4_sum_to references a countdown exercise that exists nowhere in the course Remove the dangling reference; introduce recursion fresh
10 tuples Lists * deref among syntax "we haven't formally introduced yet" — but it was taught in the hashmaps chapter Reword; turn it into a callback to hashmaps
14 structs "the same ownership rules from the ownership chapter apply" — that chapter (memory & ownership) comes after this one Point to the moves and borrowing chapters (which precede it)
19 password validator Intro snippet uses ? in a String-returning function (won't compile; the chapter intro uses .unwrap() for the same code) Use .unwrap()
19 password validator References PasswordAdvisor, a type never defined anywhere Drop the specific name
23 smart pointers Says Box<dyn Error> is something "you'll meet in the ? operator chapter" — that chapter is earlier and defers Box<dyn Error> to the env-file parser chapter Point to the env-file parser chapter, where it's actually introduced

Validation

  • ./scripts/check-solutions.sh — 75/75 solutions compile + tests pass
  • ./scripts/check-examples.sh — all chapters in their expected state

Notes / deliberately left alone

  • The const fn in the structs chapter's scaffolding initially looked like an unexplained concept, but it's required to satisfy clippy's missing_const_for_fn under the examples check's -D warnings. Reverted to respect the repo's lint policy.
  • Chapter 03's count_evens exercise uses &[i32] slices before the borrowing (05) and vectors (08) chapters. This is consistent with the documented "ownership spiral" design (introduce briefly at point of use, with a hint), so I left it; flagging here in case you'd rather restructure it.
  • Chapter 24's quiz covers Rc/Arc/RefCell from the smart-pointers chapter, which is marked bonus. A learner who skips the bonus would meet those cold in the quiz. Not changed (design call), noted for awareness.

mre added 2 commits June 21, 2026 22:08
Audit chapters for concepts used before introduction and misplaced/dangling cross-references:

- strings: retitle 'Your first function' (reader wrote functions in the integers chapter already)
- functions: drop dangling reference to a non-existent 'countdown' exercise; introduce recursion fresh
- tuples: stop claiming '*' deref is not yet introduced (it was taught in the hashmaps chapter)
- structs: point to the moves/borrowing chapters, not the ownership chapter that comes later
- password validator: fix '?' in a String-returning snippet (would not compile; matches intro's .unwrap()); drop reference to undefined 'PasswordAdvisor'
- smart pointers: Box<dyn Error> is introduced in the env-file parser chapter, not the earlier '?' operator chapter
- conditionals/loops: introduce the &[i32] slice at point of use in count_evens, before the borrowing and vectors chapters cover slices/references properly
- quiz: correct the 'longest' lifetime question (the return is bound to *no longer than* the shorter input, not 'at least as long as' it)
- quiz: drop smart-pointer content (RefCell::borrow, Rc/Arc/SharedPtr) so learners who skip the bonus smart-pointers chapter aren't tested on it
@mre mre merged commit 6bf6810 into main Jun 21, 2026
@mre mre deleted the review/concept-continuity branch June 21, 2026 20:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant