--- title: "Computing for Emerging Adults" author: "Michael Gannotti" lang: en-US date: "12 October 2026" --- ![Cover: COMPUTING FOR EMERGING ADULTS, Michael Gannotti](art/cover-titled.jpg){width=100%} \newpage # Computing for Emerging Adults {.unnumbered} Michael Gannotti *A homeschool guide to computing for ages 15–18: specs, Python and Java, testing, data, the web and Git, security, AI, and the transcript. Book 3 of the SMF WisdomForge Computing series.* Illustrated edition, 12 October 2026. Notes run in one series at the back; the superscript numbers link to them. The images are original still lifes, with no people and no brands. # Contents {.unnumbered} - Welcome - How to Use This Book This Week - If You Only Remember Five Things - The Computing Hour - Chapter 1 — What Computing Looks Like at 15–18: Specs, Algorithms, and Running Your Own Work - Chapter 2 — Python as a Tool: Programs That Read, Compute, and Write - Chapter 3 — Testing and Debugging: Proof Before Pride - Chapter 4 — Objects and Classes: The Bridge to Java - Chapter 5 — Data: Questions, Tables, and Databases - Chapter 6 — Building for People: The Web, the Command Line, and Git - Chapter 7 — Systems, Networks, and Security: What You May and May Not Touch - Chapter 8 — Working With AI: How It Learns, Where It's Wrong, and Whose Work It Is - Chapter 9 — Credit and the Transcript: Records, Portfolio, AP, and Dual Enrollment - Chapter 10 — Resources - A Note on Sources - Notes \newpage # Welcome Here is a picture. It is an illustration, not a real family. A sixteen-year-old's spec page sits on the kitchen table beside a laptop. It is one sheet, handwritten, with a coffee ring in the corner. At the top it says what the program is for: a tool that totals the pages in a reading log. Below that come the inputs, the outputs, three examples, and a last line that says, "Done when all three examples pass and Mom can use it without asking me anything." On the screen, a test has just failed. The third example, the one with a blank line at the end of the file, crashed the program. In a notebook beside the laptop, the student has already written the Debug Log line: "Expected 817. Actual: ValueError on the last line. Guess: the blank line has no comma. Try: skip empty lines." Nobody has touched the code yet. Nobody is upset. The parent, who does not program, is reading the log and asking one question: "How will you know the fix worked?" That table is what this book is for. ## Who this book is for This book is for the parent of a fifteen- to eighteen-year-old who wants a real computing year at home. You may write code for a living. You may never have opened a terminal. Either way, your job in these pages is the same, and it is one you can do well: you ask good questions, you use the program like a stranger would, you read the log, you keep the safety rules, and you sign the records. It is also for the student, who will run most of it. At this age, computing becomes your own work. You decide what to build, you write down what it must do, you run the session, you keep the history, and you defend the result. Every chapter has a section written to you directly. Read it on your own. It assumes you are capable, because you are. Many adults feel unsure about code. That is fine, and it changes faster than you'd think. You do not need to be ahead of your student. You need to be curious beside them. ## The line the whole book runs on Every chapter, every session, and every check in this book comes back to one sentence: **Specify it before you build it; predict before you run; debug before you rewrite; explain it before you call it yours.** *Specify it before you build it* means a short written spec (a description of what the program must do, with examples and a line saying what "done" means) comes before any code. *Predict before you run* means your student writes down what the program will do before pressing run, and then compares. *Debug before you rewrite* means red text is a clue, not a verdict. Your student reads it, writes what they expected and what actually happened, changes one thing, and logs it. Starting over is a decision made after evidence, not a reaction to panic. *Explain it before you call it yours* means ownership is tested out loud. If your student can't explain a line, it isn't theirs yet, however it was made. That matters more than ever now that a chatbot can produce a screenful of code in seconds. What a tool makes is made by a tool. ## What your student will learn Over a year, your student will learn to write a spec and build to it in Python, then in Java. They will prove their programs work with tests, debug calmly from evidence, and keep every change in Git (a tool that records the history of a project). They will ask honest questions of data with a real database, build a web page a real person can use with a keyboard alone, and work in the terminal like a professional. They will learn how computers and networks work and how to protect their own systems ethically, only on systems they own. They will learn how AI systems learn, where they go wrong, and how to use them without handing over ownership of their work. And they will turn all of it into a record that a stranger can read: hours, artifacts, checks, a portfolio, and a transcript line. ## You are not alone Homeschooling is ordinary now. About 3.4 percent of American students in kindergarten through grade 12 were homeschooled in the 2022–23 school year, well over a million and a half students.^[1](#note-1)^ Families teaching high-school computing at home are part of that number. Co-ops, libraries, community colleges, and working programmers down the street are all part of how they do it, and this book shows you how to use each one. ## What this book will not do It will not hand you a 180-day script. It gives you a session that works, a week to start with, and a bank of 100 activities to build from. You choose. It will not promise an AP score, a college admission, or a job. It explains how AP and dual enrollment work for homeschoolers, and it treats both as options. It will not promise that coding sharpens every other subject. Learning to program teaches programming, and that is plenty. Other benefits are possibilities, not promises, and the book says so once and then gets on with teaching. It will not sell you a curriculum, rank products, list prices, or issue certificates. It will not invent a course title with its name on it. Your student's transcript will say something a registrar recognizes, such as "Computer Science." It will not reprint an earlier book. Everything here is written for fifteen- to eighteen-year-olds. ## Where this book sits This is the third title in the SMF WisdomForge Computing series. *Computing for Little Thinkers* covers ages 5 to 10, and *Computing for Young Minds* covers 11 to 14. After this book comes *Computing Refresh for Adults*, for the parent who'd like their own turn. A student who is new to the series starts at Chapter 1 and is fine. A student coming from *Young Minds* should still start at Chapter 1, because specs are new, and can then move quickly through Chapter 2. ## Where to begin Turn to "How to Use This Book This Week." It gives you five days, starting Monday. Then read **The Computing Hour** together, out loud if you like. It is the session this whole book runs on, and your student will be leading it by Friday. Find a pencil, a stack of index cards, and one clean sheet of paper. That sheet is going to become a spec. — Michael Gannotti \newpage # How to Use This Book This Week You can start on Monday. You don't need to read the whole book first, and you don't need to buy anything. You need a computer that can run Python (a shared family computer is fine), a notebook for the Debug Log, a stack of index cards, and about four hours across the week. ## This week | Day | What you do | Cards | Time | |---|---|---|---| | Monday | Read **The Computing Hour** together. Sign the family security rule and the AI rule. Set up the folder plan and two places. Write and initial the Monday plan (15–16). | SEC-01, SYS-03, PLAN-01 | 45–60 min | | Tuesday | First Hour: a tiny program from a one-page spec. Predict the output before every run. | SPEC-01, PY-02, BUG-01 | 50–70 min | | Wednesday | Unplugged: two ways to search a stack of cards, with step counts. A short Cold Trace for a baseline. | ALG-01, AS-01 | 30–40 min | | Thursday | Second Hour. You are first user. | SPEC-02, TEST-05, BUG-05 | 50–70 min | | Friday | Ten-minute audit. Read the Debug Log together. Choose next week's goal. | PLAN-02 | 15 min | **Monday.** Read **The Computing Hour** out loud, taking turns. Then sign two short pages. The first is the family security rule (SEC-01): your student practices security only on systems they own and toy apps they built, never anyone else's, even "to help." Chapter 7 teaches it in full, but it goes on the wall in week one. The second is the AI rule from the AI box in **The Computing Hour**, copied in your student's handwriting. Then make the folder plan: one folder for the course, one subfolder per project, and a second copy somewhere else, such as a USB stick or a family drive. That is "two places" (SYS-03). Finish with the Monday plan (PLAN-01): this week's goal, the first spec, and the one risk to watch. At 15–16 you initial it. **Tuesday.** The first Hour. Your student writes a one-page spec (SPEC-01) for something tiny: a tip calculator, a reading-log totaler, a unit converter. Then they predict what the first run will print (PY-02), run it, and compare. When something surprises them, they write the Expected/Actual line (BUG-01) before touching the code. Use the step names out loud: Specify, Predict, Build and Test, Debug and Log, Review, Ship and Explain. **Wednesday.** No screen. Sixteen numbered cards, two ways to find one of them, and a tally of the flips (ALG-01). Then a ten-minute Cold Trace (AS-01): a short program on paper, traced without help, with the predicted output written at the bottom. Date it and file it. It is not a grade. It is the "before" picture you'll compare against all year. **Thursday.** The second Hour, on the same program or a new one. This time your student adds examples to the spec before writing code (SPEC-02), and you are the first user (TEST-05): you use the program like a stranger would and report what happened, without fixing anything. Your student logs what you found in the Debug Log (BUG-05). **Friday.** Fifteen minutes. Read the week's Debug Log together. Count the hours. Ask, "What would you do differently next week?" and write down the answer. Choose next week's goal (PLAN-02). ## The two bands Inside each chapter, the book speaks of two bands, **15–16** and **17–18**. Place by skill, not birthday. **At 15–16,** you're in the room for the Hour. You initial Monday's plan, ask one question about the spec, and act as first user every session. **At 17–18,** your student hands you or emails you the plan on Monday, runs the Hour alone, and you read the Debug Log the same day. You're first user once a week. Some cards are marked **ready 16**. Those are 17–18 moves that a sixteen-year-old with the skill can take. A seventeen-year-old who is new to programming can run the whole year at the 15–16 pace, and that is fine. ## How each chapter is built Every teaching chapter (Chapters 1 through 8) uses the same eight headings, in the same order: 1. **Why this matters** — about a page on what the chapter is for. 2. **For the parent: understand it yourself** — the idea in plain words, then precisely; one standard quoted; the wrong answers you should learn to hear; a five-minute warm-up for you. 3. **How to teach it this week** — the session shape, exact sentences to try, and the first activity. 4. **Practice that actually builds learning** — named try-its at home and out of the house, the talk box, and one wrong example to diagnose. 5. **For the student** — a longer section written to your student. 6. **If it isn't clicking** — what you see, what it usually means, and what to try next. 7. **Tools, including AI** — what's different in this chapter, pointing back to the AI box. 8. **What "done enough" looks like** — a checklist, including the checks. ## Reading a try-it box Each activity has a heading such as *In-home — SPEC-01 The One-Page Spec* or *Out-of-home — OUT-01 Algorithms in Public*. The code matches the activity bank. Inside the box you'll find the **time**, the **materials**, a **safety and privacy** line, **the fun**, **the skill**, and **the crumb**, which is what to save for the record. Then comes "How it goes," with band notes where they matter. About 44 of the book's 100 activities need no screen at all. That is on purpose. Specs, traces, tests, diagrams, and threat models are paper work at every age, including for professionals. ## Reading a talk box Each teaching chapter has one talk box. It gives you an opening question with no answer to recite, five follow-ups, how to wait, what a stuck silence usually means, and one "don't say / say instead." The shape is explained once in **The Computing Hour**. ## Where the checks live The book's seven checks (AS-01 through AS-07) appear in each chapter's "done enough" list and gather in Chapter 9 with the portfolio. All of them are done without AI. None of them is a test battery or a percentile. They are dated pieces of evidence that your student can do the work alone. ## What to save from week one - The signed family security rule and AI rule - The initialed Monday plan - The first spec, with any marks you made on it - The Wednesday Cold Trace, dated - The first Debug Log page, with minutes for each day - The program file, saved in two places That is the beginning of a transcript. Chapter 9 shows how it grows. ## Low-device homes One shared computer works. Siblings can stagger Hours or pair up (Chapter 1 shows how). Chapters 1 through 5 run fully offline. A whole Computing Hour can also run at a public library (OUT-02, in **The Computing Hour**), which is how many families handle publishing in Chapter 6. ## When life happens A week with a move, a new baby, or a hard diagnosis can be a week of index cards and Cold Traces. Pick up where you left off. The Debug Log will remember where that was. \newpage # If You Only Remember Five Things If the week goes sideways and you read nothing else, keep these five. The rest of the book is these five, done carefully. **Specify it before you build it; predict before you run; debug before you rewrite; explain it before you call it yours.** ## 1. Specify it before you build it. Before any code, your student writes a short spec: what the program is for, who uses it, what goes in, what comes out, the rules, two or three examples (one of them an odd or boundary input), and one line that says what "done" means. One page is plenty. A spec is a tool, not paperwork, and it changes as your student learns. If there's no done line, nobody can say whether the work is finished, including your student. ## 2. Predict before you run; debug before you rewrite. No run without a written prediction. When the program surprises them, your student writes Expected/Actual, makes a guess, changes one thing, runs it again, and writes a line in the Debug Log. Red text is a clue with a line number. Starting over is allowed, but only after the log says why. ## 3. Explain it before you call it yours. Every Hour ends with the exit line: "I specified… I predicted… It did… Next I'd change…" and then "Help I used: …", said every time, even when the answer is "none." A tutorial, a sibling, the documentation, you, an AI tool: all of it counts, and none of it is shameful. If your student can't explain a line, it isn't theirs yet. AI output is made by a tool, never filed as your student's work. ## 4. Tests, two places, and a Debug Log are the record. From Chapter 3 on, a project without tests isn't done. Every file lives in two places. The Debug Log carries the minutes for each day, and the minutes become hours. About 150 hours makes one full credit, and Chapter 9 turns the record into a transcript line a stranger can read. ## 5. Security practice only on your own systems; AI coding help in the editor off through 16. Your student practices security only on systems they own and toy apps they built, under a signed family security rule. Never anyone else's system, even "to help," even with a friend's say-so. AI coding assistants inside the editor stay off through age 16. At 17, your student may turn one on for one named project, after passing a closed-book Build From a Blank (AS-04). AI is off for every check, at every age. The full rule is in the AI box in **The Computing Hour**. That's it. Specify, predict, debug, explain, and keep honest records. You can do this. \newpage # The Computing Hour ![A desk by a window set for the Hour: an open laptop showing indented colored bars, a handwritten spec page, an open Debug Log notebook, an index card, a pencil and a mug — still life, no people, no logos, no readable text.](art/computing-hour-setup.jpg){width=100%} The Computing Hour is the session this whole book runs on. It has six steps, the same six every time, and your student runs them. Learn it this week, and the rest of the book will make sense. **Specify it before you build it; predict before you run; debug before you rewrite; explain it before you call it yours.** ## The six steps | Step | 15–16 | 17–18 | What the student does | What the parent does | |---|---|---|---|---| | **Specify** | 5–10 min | 5–10 min | Writes or updates today's spec: goal, inputs and outputs, two examples, the done line | 15–16: reads it and asks one question; initials Monday's plan | | **Predict** | 2–5 min | 2–5 min | Writes what the next run will do | Asks "Why?" and waits | | **Build and Test** | 20–35 min | 30–50 min | Writes code in small steps; runs the tests after each change | Stays off the keyboard; stays available | | **Debug and Log** | 5–15 min | 5–15 min | Expected/Actual, a guess, one change, a Debug Log line | Uses the rescue order, only if asked | | **Review** | 5–10 min | 5–10 min | Rereads the change against the spec; saves with a real message; notes the next test | 15–16: first user every session | | **Ship and Explain** | 3–5 min | 3–5 min | Says or writes the exit line | Listens; 17–18: reads the log the same day | At 15–16 the Hour runs about 50 to 70 minutes with you in the room. At 17–18 it runs about 60 to 90 minutes, and you read the log the same day. Project days may run longer with a movement break in the middle. Stop while it's going well; a passing test is a fine place to end. **Specify.** The spec is a short written description of what the program must do, with examples and a line that says what "done" means. Later in a project, this step is a two-minute update. Chapter 1 teaches specs in full. **Predict.** Before every run, your student writes one line: "I predict it will print…" (PY-02). A wrong prediction is the most useful thing that can happen in an Hour; it shows exactly where your student's picture differs from the program. **Build and Test.** Small steps: a few lines, a run, a check against the spec's examples. From Chapter 3 on, that means real tests (written checks that compare what the program does with what it should do). **Debug and Log.** When something surprises your student, the first move is a pencil: Expected/Actual, a guess, one change, a rerun, a Debug Log line. **Review.** Your student rereads what changed today and holds it up against the spec. They save the work with a message that says what changed, such as "Format money to two decimals" rather than "stuff." (In Chapter 6 that save becomes a Git commit.) They note the next test to write. **Ship and Explain.** The Hour ends with the exit line, said aloud or written in the log: "I specified… I predicted… It did… Next I'd change…" and then "Help I used: …" "Help I used" is said every time, even when the answer is "none." A tutorial, a sibling, the documentation, you, an AI tool: all of it counts, and none of it is shameful. ## Here's how one Hour might go This is an illustration, a composite, not a real family. It's Monday. A fifteen-year-old's spec for a tip calculator says: put in a bill and a percent; get out the tip and the total, in dollars and cents. Examples: a bill of 40.00 at 20 percent gives a tip of 8.00 and a total of 48.00; a bill of 0 at 20 percent gives 0.00 and 0.00. Done when both examples pass and a stranger can use it without help. Her father initials it and asks one question: "What happens if someone types 20%?" She adds a third example and writes "should say please type a number." Predict: "It'll print 8.0, not 8.00." Build and Test: ```python bill = 40.00 percent = 20 tip = bill * percent / 100 total = bill + tip print(tip, total) ``` It prints `8.0 48.0`. Her prediction was right, and the spec says dollars and cents, so the test fails. Debug and Log: Expected 8.00 and 48.00; Actual 8.0 and 48.0; guess: Python doesn't know these are money. She looks up formatting, changes the last line to `print(f"{tip:.2f} {total:.2f}")`, and it prints `8.00 48.00`. The Debug Log gets a line and 55 minutes. Review: the change matches the spec. She saves with the message "Format money to two decimals." Her father, as first user, types 20% and watches it crash, which she already knew. She writes it down as the next test. Ship and Explain: "I specified a tip calculator with three examples. I predicted it would drop the zero. It did. Next I'd change it to reject a percent sign politely. Help I used: the Python documentation on formatting." ## The Debug Log The Debug Log (BUG-05) is a notebook or a plain text file, kept all year. Each entry is dated and short: - **Symptom:** what went wrong, in one line - **Expected/Actual:** what your student expected, and what happened (BUG-01) - **Guess:** why they think it happened - **Test:** the one change they tried - **Fix:** what worked, or "not yet" - **Lesson:** one sentence, if there is one - **Minutes:** how long the Hour ran The minutes add up to hours, and the hours to credit. At 17–18, a five-minute conversation about one entry is often the best teaching of the week. ## First user The first user (TEST-05) is you. You sit down at the program and use it like a stranger would, someone who didn't write it and doesn't know what it's supposed to do. Then you report what happened, plainly, without fixing anything. Try this exact sentence: "I'm going to use it like a stranger. I won't fix anything; I'll just tell you what happened." Then: "It asked for the bill. I typed forty dollars, in words. It crashed. Over to you." You don't need to know any code to do this well; you'll type the things real people type. ## Who runs it **15–16.** Your student is the session lead from the first week. They write the spec, keep the clock, keep the Debug Log, and say the exit line. You're in the room. You initial Monday's plan (PLAN-01), ask one question about each new spec, and you're first user every Hour. **17–18.** Your student plans the week and hands you or emails you the plan on Monday. They run the Hour on their own. You read the Debug Log the same day, ask about one entry, and act as first user once a week. Place by skill, not birthday. A seventeen-year-old who is new to all of this may want the 15–16 shape for a semester. In the chapters, "ready 16" marks 17–18 moves some sixteen-year-olds can take. ## The rescue order When your student is stuck and asks for help, use the same order every time: **ask → wait → hint → short demo on your own copy → hand it back.** Ask a real question: "What did you expect on that line?" Wait. Count to five in your head, and longer if they're reading code. Offer a hint that points without solving: "Look at what the last line of the red text says." If a demo is truly needed, show it on your own paper or your own copy of the file, then close it and hand the turn back. Your hands stay off your student's keyboard. A program they fixed is theirs. If you write code yourself, this is the hardest part of the book. Resist fixing. ## When the Hour goes wrong | If the Hour looks like… | Try this | |---|---| | No spec, just typing | "Write three lines first: what goes in, what comes out, how you'll know it's done." Then start. | | Red text and panic | Read the last line of the error aloud first. What's its name? Which line number? Write Expected/Actual. | | "I'm deleting it and starting over" | "Before you start over, what does the Debug Log say you tried?" Save a copy, log first, then decide. | | A chunk of AI-written code appeared | Stop. Fill in the Whose Work Is It? card (AI-06) for that part. Then walk through it line by line, or take it out. | | The project is too big to finish | Scope it down (PLAN-03, Chapter 1): what version could ship in two weeks? | | A flat, bored Hour | Switch to an unplugged card, or ask your student to teach you the hardest line. Boredom often means they're ahead. | | You took the keyboard | Hand it back and say so: "That was me fixing it. Your turn." | | It ran long and nobody wants to stop | Stop at the next passing test. Write the next step in the log for tomorrow. | ## The try-it shape Every named activity in the book is a try-it, and every try-it box has the same shape. The heading carries its bank code and name, such as *In-home — SPEC-01 The One-Page Spec* or *Out-of-home — OUT-02 Library Computer Hour*. Then: - **Time** — about how long it takes - **Materials** — what to gather - **Safety and privacy** — anything to watch - **The fun** — why it's worth doing - **The skill** — what it builds - **The crumb** — what to save for the record Then **How it goes**, with band notes (**15–16**, **17–18**, **ready 16**) where they matter. Each teaching chapter has at least one in-home try-it and one out-of-home try-it. Here's one worth knowing in week one. ### Out-of-home — OUT-02 Library Computer Hour - **Time:** about 50 minutes - **Materials:** a library card, a USB stick or a family cloud folder, the spec on paper - **Safety and privacy:** log out of everything before you leave; save nothing to the library computer - **The fun:** a change of scene, and proof that the work doesn't depend on one machine - **The skill:** running a whole Computing Hour on a public computer and leaving no trace - **The crumb:** the file saved in two places **How it goes.** Your student brings the spec on paper and runs the whole Hour on a library computer, using a browser-based Python editor or whatever the library offers. At the end they save the file to the USB stick or family folder, check that it opened, log out of every account, and close the browser. At 15–16 you sit beside them. At 17–18 they can go alone, and the crumb is the file arriving in its two places at home. ## The talk-box shape Every teaching chapter has one talk box, and its shape never changes. **The opening** is a real question. It asks about your student's own spec, prediction, evidence, or judgment, and it has no answer to recite. **Five follow-ups**, always in these five kinds: 1. **Prediction:** "What will it do?" 2. **Evidence:** "What did you see that makes you say that?" 3. **Location:** "Which line is the last one that did what you expected?" 4. **Change:** "What's the one thing you'd change?" 5. **Revision:** "You can change your answer. Run it again." **How to wait.** Count to five in your head. When the question is about code on the screen, let them read as long as they need. Look at the code, not at your student. **What a stuck silence usually means.** Rarely that your student doesn't care. More often the question was vague or there was no wait; your student fears looking wrong in front of a parent (keep every comment about the code); they're waiting for you to fix it because you have before; there's no written spec or prediction to compare against; or the screen is louder than the question (lower the lid for a moment). Sometimes your student is ahead and bored; ask them to teach it. **Don't say / say instead.** Each chapter gives one. For example: don't say "That's wrong"; say "Show me the line where it stops doing what you expected." ## Family safety basics These are ordinary and non-negotiable. Chapters point back here; Chapter 7 teaches security in depth and Chapter 8 teaches image safety. - **The family security rule** (SEC-01). Your student practices security only on systems they own and toy apps they built. Never anyone else's system, even "to help," even with a friend's say-so. The law applies to teenagers. The rule is one page, signed by both of you, and it goes up in week one. - **First names only.** Anything shared beyond the family carries first names only: no faces, no school, no town. Screenshots are cropped to the work. - **Your student holds their own passwords,** on their own accounts, with long passphrases and two-step login (a password plus a second thing, such as a code or a key) turned on. You and your student make a recovery plan together, so a lost phone isn't a lost account. - **Stop, Save, Tell** (SAFE-02). If anything online is threatening, pressuring, or sexual: stop replying, save it instead of deleting it, and tell a parent. Nobody is in trouble for telling. Chapter 8 rehearses it. - **Library and shared computers.** Log out of everything; save to your own drive, not the machine. - **Two places.** Every file lives in two places: the family drive or a USB stick, and one backup. Not a shared bot computer, and not a chatbot. - **Publishing is a family decision.** Nothing goes public without your yes. - **Screens out of the bedroom overnight** is a family call at this age, offered here, not imposed. ## A note on screen time The American Academy of Pediatrics asks families to make a media plan of their own rather than follow one number, putting the weight on content and on what screens crowd out: sleep, meals, movement, and homework.^[2](#note-2)^ The World Health Organization asks families to limit recreational screen time and to keep teenagers moving at least an hour a day, without giving a number for screens.^[3](#note-3)^ On sleep, the American Academy of Sleep Medicine recommends 8 to 10 hours in every 24 for teens 13 to 18.^[4](#note-4)^ These are guidelines, and they change as the research does. The Hour is purposeful school work; nearly half its activities are unplugged, and it ends with the screen closed. A late-night bug goes in the Debug Log and waits for morning. ## The AI box > **Working with AI in the Computing Hour** > > **The rule underneath everything:** your student specifies, predicts, writes, tests, and debugs. AI may explain, suggest, or check, within the service's terms and your family's rules. Anything it produces is made by a tool, not your student's work. > > **At 15–16.** Chat-style help is allowed, under the terms and with a parent nearby, *after* your student has written Expected/Actual and a guess: explain an error message, explain an idea, suggest practice problems with the answers hidden. **AI coding assistants inside the editor stay off.** > > **At 17.** Your student may turn an editor assistant on for **one named project**, after passing a closed-book Build From a Blank (AS-04). The project's README and Whose Work card say so. Every suggestion gets explained line by line before it stays (AI-05, Chapter 8). > > **At every age.** AI is off for every check: Cold Trace, Debug on the Spot, Explain Your Code, Build From a Blank, Whose Work Audit, Spec-to-Test Check, and Portfolio Defense. "Help I used: …" goes on every exit line. Generated code, text, and images are never filed as your student's work. > > **Please don't:** paste private messages, photos, names, or your address into a chatbot; upload photos of family or friends to any AI tool; use companion or role-play apps; use an AI "detector" to judge your student, because "explain it to me" is the check; trust a citation until you've opened it. > > **Why the care?** In one large study of high-school math students (not computing, and not homeschoolers), unrestricted chatbot help raised practice scores while lowering what students could do alone later; a version that gave hints instead of answers largely avoided the harm.^[5](#note-5)^ This is a useful study, not a promise that every home will see the same result. > > **If you use Grok Bot,** remember that all of your bots share one computer. Keep photos of your children and family off it, and keep your student's portfolio on a family drive.^[6](#note-6)^ > > **Age terms:** most consumer AI services set 13 as their minimum age, many require a parent's permission until 18, and at least one major one sets 18.^[7](#note-7)^ Check the current terms. > > **At 18:** a family AI agreement, written together as adults in one household (SAFE-05, Chapter 8), replaces the age rules above. **Whose work is it?** Your student's work is what they specified, wrote, tested, and can explain. Every project carries a Whose Work Is It? card (AI-06), "Whose Work card" for short: who or what helped, what was asked, what came back, what was kept, what was changed, and how it was tested. A card that says "none" is a perfectly good card. ## Dose honesty There's no national rule for how many hours a homeschooler should code. A common homeschool guideline counts about 150 hours of work for one full high-school credit in a core subject, and about 120 hours for an elective; it's a guideline, not a law.^[8](#note-8)^ In practice, about four Computing Hours a week across a 36-week year, plus try-its and projects, makes a full credit. Two Hours a week makes a half credit, and that's a real course too. Chapter 9 shows how to count. ## The life of the habit Keep the Debug Log going all year. Do a Cold Trace (AS-01) once a month: a short program traced on paper, alone, dated. Finish a project every four to six weeks. Hold a demo day once a semester for family, a co-op, or a grandparent on a video call. None of this is a schoolroom invention. Specifying, testing, logging, reviewing, and explaining your work to a colleague is how working programmers already work. The Computing Hour is the same habit, in a smaller room. ## Things to say 1. **Opening Specify (15–16).** "What's the goal today, and how will you know it's done?" Wait. Your student reads you the done line. 2. **Predict.** "Write down what you think it will print. Then run it." 3. **Red text.** "Read me the last line. What's the error's name? Which line?" Wait. "What's your best guess?" 4. **The urge to rewrite.** "Before you start over, what does the Debug Log say you tried?" 5. **Review.** "Show me what changed since last time. Does the spec still say the same thing?" 6. **Ship and Explain.** Your student: "I specified… I predicted… It did… Next I'd change… Help I used: …" ## Ready to begin Chapter 1 starts where every Hour starts: with a spec. Find a clean sheet of paper. \newpage # Chapter 1 ## What Computing Looks Like at 15–18: Specs, Algorithms, and Running Your Own Work ![A one-page spec on a clipboard with ruled boxes and a check box, beside a flowchart sketch, index cards and a pencil — still life, no people, no logos, no readable text.](art/ch01-opener.jpg){width=100%} ## Why this matters Here is a picture. It is an illustration, not a real family. A seventeen-year-old has been asked to build a chore rotation tool for his younger sisters. He opens a laptop, and his mother, who has read this chapter, closes it again. Gently. "Spec first," she says, and slides a sheet of paper across the table. He writes for twelve minutes. At the top: "A tool that assigns four chores to three sisters across seven days, fairly." Then the inputs (names, chores, days), the output (a printed week), the rules (nobody gets dishes two days running), three examples, and a last line: "Done when every sister gets every chore at least once in a week, and the youngest can read the printout herself." His mother reads it the way a stranger would. "What does 'fairly' mean?" He crosses it out and writes what he actually means. "What happens when someone's away for the weekend?" He hadn't thought of that. He writes it down as a question for later. By the end of the week the tool works. The spec has changed twice, and both changes are written on the page with a date. When his sisters argue that the rotation isn't fair, he doesn't argue back. He shows them the done line and asks which example they'd like him to add. That is computing at fifteen to eighteen. The programs are bigger, the languages are real, and the tools are the ones professionals use. But the deepest change isn't technical. At this age, the work becomes your student's own. They decide what to build. They write down what it must do. They run the session, keep the history, and defend the result. You stop being the person who plans the lesson and become the person who asks, "How will you know it's done?" This chapter gives that change its first tools. The spec comes first: a short written description of what a program must do, with examples and a line saying what "done" means. Then algorithms: the exact steps inside the spec, which can be counted, compared, and traced on paper before a single line is typed. Almost all of it needs no screen. And all of it rests on the line the book runs on: **Specify it before you build it; predict before you run; debug before you rewrite; explain it before you call it yours.** This chapter is about the first clause. The rest of the book is about the other three. ## For the parent: understand it yourself ### The plain picture A spec is a promise written before the work starts. It says what the program is for, who will use it, what goes in, what comes out, what rules it follows, and how you'll know it's finished. It includes two or three examples: "if someone types this, the program should do that." At least one example is an edge case (an input at the boundary, or an odd one a careless user might type). An algorithm is the exact list of steps that gets from the input to the output. Recipes, driving directions, and the rule your family uses to decide who sits in the front seat are all algorithms, some better written than others. A computer needs an algorithm with no gaps, because it will do exactly what it's told, in order, every time, and never guess what you meant. People sometimes call this whole way of working computational thinking: breaking a problem down, spotting patterns, setting aside detail that doesn't matter, and writing exact steps. This book uses plain words for it from here on. ### The precise picture A good spec describes **behavior, not code**. "The program shows the cheapest of three prices" is behavior. "Use a for loop" is code, and it belongs in the program, not the spec. A spec that names its examples precisely ("input: 4, 9, 2 → output: 2") is already halfway to a set of tests, which is exactly what Chapter 3 will turn it into. Algorithms can be compared. Some take more steps than others to do the same job, and the difference grows as the job grows. Looking for one card in a stack of sixteen by flipping each card in turn takes up to sixteen flips. If the stack is sorted, you can start in the middle and throw away half the stack with each flip: no more than five flips for sixteen cards, and only one more when the stack doubles to thirty-two. That's the difference between linear search and binary search, and your student will count it by hand this week. Some algorithms always give the same output for the same input (deterministic). Others involve chance and might give a different answer each time (probabilistic). A sorting rule is the first kind. A shuffled playlist is the second. That distinction matters a great deal in Chapter 8, because AI systems that write text are probabilistic. The national standards many schools use for high-school computer science cover ages 14 to 18 and put it this way for algorithms: students should "Evaluate algorithms for efficiency, correctness, and clarity, using metrics or test cases."^[9](#note-9)^ That is the whole chapter in one sentence. Efficiency is the step count. Correctness is the spec's examples. Clarity is whether someone else can follow it. ### An honest word about the evidence You'll hear that learning to code improves thinking in general. The best summary of the research is more modest. A large review of studies found that learning to program does carry over to some other kinds of thinking, moderately, and most to skills close to programming itself; the effect was smaller when programming was compared with other active lessons, and smallest for school achievement and reading.^[10](#note-10)^ This is a useful study, not a promise that every home will see the same result. Learning to program teaches programming, and that is reason enough. Specs, in particular, are a craft. They make your student a better builder of software, and the book promises nothing beyond that. ### Wrong answers you should be able to hear You don't need to know any code to hear these. Each one has a question that turns it around. - **"It should just work."** There's no done line. Ask: "How will you know it's done? Write it down." - **"Use a loop to go through the list."** The spec describes code, not behavior. Ask: "What will the person using it see?" - **Examples that are all ordinary.** No edge case. Ask: "What would a stranger type? What about nothing at all?" - **"Binary search is always better."** Only if the data is sorted first. Ask: "What does it need before it can start?" - **"I'll figure out the steps as I type."** The algorithm lives only in their head. Ask: "Walk me through it on paper, one step at a time." ### A five-minute warm-up for you Before you teach this, write a spec for something you do every day: making coffee, starting the car, or the rule for whose turn it is to pick the movie. Include a done line and one edge case ("What if we're out of milk?"). Then hand it to your student and ask them to follow it literally. You'll laugh, and you'll understand the chapter. ## How to teach it this week The first week of Chapter 1 fits inside the plan in "How to Use This Book This Week." Here's the session shape for a spec day, using the Hour's step names. **Specify (most of the Hour on day one).** Your student writes a one-page spec for something small. Hand them the sheet and say, "Before any code: what's it for, who uses it, what goes in, what comes out, and how will we know it's done?" **Predict.** On a spec day, the prediction is about the spec itself: "Which part of this do you think I'll get stuck on when I follow it?" **Build and Test.** On paper. You follow the spec literally (SPEC-03, below), and your student watches where you stall. **Debug and Log.** Every stall becomes a fix written in a second color, and one line in the Debug Log: "Expected: Mom would get two slices. Actual: she got the whole loaf. Fix: 'take out exactly two slices.'" **Review.** Your student reads the spec start to finish one more time. Is there still a done line? Is there an edge case? **Ship and Explain.** "I specified… I predicted… It did… Next I'd change…" and "Help I used: …" ### In-home — SPEC-01 The One-Page Spec - **Time:** 20 minutes - **Materials:** one sheet of paper, a pencil, a second-color pen for later - **Safety and privacy:** if the program involves family members, first names only - **The fun:** finding out how much you know about a program before it exists - **The skill:** purpose, user, inputs, outputs, rules, and what "done" means, before any code - **The crumb:** the signed spec page **How it goes.** Your student picks a small program they'd actually use: a tip calculator, a reading-log totaler, a timer for practice sessions, a chore rotation. On one page they write six things, each with a short heading. 1. **Purpose:** one sentence. What is it for? 2. **User:** who will use it? ("My grandmother, on her tablet" is a better answer than "people.") 3. **Inputs:** what goes in, and in what form? 4. **Outputs:** what comes out, and in what form? 5. **Rules:** what must always be true? What must never happen? 6. **Done when:** one line that a stranger could check. They sign and date the bottom. You read it and ask one question. Not a correction: a question. "What happens if the bill is zero?" is a good one. **15–16:** you ask one question, and your student revises. You initial the page. **17–18:** your student writes the spec alone and hands it to you on Monday with the week's plan. You read it the way a stranger would and write your one question in the margin. ### Fading your help In week one, you ask the done-line question out loud. By week three, your student writes the done line before you get there. By the end of the semester, they're asking you what you'd type as an edge case, and you're the one who has to think. That's the direction this book always moves: from your question, to their habit, to their judgment. ### Band moves **15–16:** one page; one question from you; the spec is written before the first Hour of each project and updated in each Specify step after that. **17–18:** user stories with acceptance lines (SPEC-04) for anything someone else will use, and a spec diff (SPEC-05) at the end of each project, comparing what the spec said with what shipped. ## Practice that actually builds learning Practice in this chapter goes in two directions: making specs sharper, and making algorithms countable. Start each with one kind of card at a time (blocked practice) for a week or two, then mix them so your student has to decide which tool fits. ### In-home — SPEC-02 Examples Before Code - **Time:** 15 minutes - **Materials:** the spec from SPEC-01, a ruled sheet for a table - **Safety and privacy:** no real names or numbers from anyone outside the family - **The fun:** inventing the inputs a careless or creative user might type - **The skill:** writing input → expected output examples, including edge cases, as part of the spec - **The crumb:** the example table **How it goes.** Under the spec, your student draws a table with two columns: *If the input is…* and *The program should…*. They fill in at least three rows. One is ordinary. One is at a boundary (zero, the largest allowed value, an empty list). One is something a stranger might type ("twenty," "20%," a space at the end, nothing at all). Every row says exactly what should happen, including "politely say please type a number." **15–16:** three rows, one of them an edge case. **17–18:** five rows, and your student marks which rows would make good automatic tests later (Chapter 3). ### In-home — SPEC-03 The Literal Reader - **Time:** 15 minutes - **Materials:** a written spec or set of instructions, a second-color pen; for the first round, a sandwich kit or a deck of cards - **Safety and privacy:** no knives or heat in the literal-reader round; keep it to cold food or cards - **The fun:** watching a parent follow instructions with total, deadpan literalness - **The skill:** repairing every ambiguity in a written spec - **The crumb:** the marked-up spec in two colors **How it goes.** For the first round, your student writes instructions for something physical: "make a peanut butter sandwich" or "sort these ten cards from lowest to highest." You follow them exactly as written. If the instructions say "put the peanut butter on the bread," you put the jar on the loaf. Every place you stall or go wrong, your student writes a fix in the second color. Then swap to a real spec, the one from SPEC-01, and do it again on paper: you play the program and do only what the spec says. **15–16:** the sandwich round first, then their own spec. **17–18:** skip the sandwich if they've done it before, and swap to a spec for a program another family member will actually use. Ask that family member to be the literal reader. ### In-home — SPEC-04 User Story and Acceptance Test - **Time:** 15 minutes - **Materials:** index cards - **Safety and privacy:** first names only on cards - **The fun:** writing like a professional team does - **The skill:** "As a …, I want …, so that …" with a checkable acceptance line - **The crumb:** the story card **How it goes.** On each card, your student writes one user story in a fixed form: "As a [user], I want [something], so that [reason]." Underneath goes an acceptance line that anyone could check: "Given four names and seven days, every name appears at least once." A project usually has three to six stories. Your student sorts them into "must have" and "nice to have" and builds the must-haves first. **17–18:** for any project someone else will use. **Ready 16:** a sixteen-year-old who writes clean one-page specs can start here. ### In-home — SPEC-05 Spec Diff - **Time:** 15 minutes - **Materials:** the original spec, the finished program, the Debug Log - **Safety and privacy:** nothing new to watch - **The fun:** finding out what you actually built - **The skill:** comparing what the spec said with what shipped, and writing the change note - **The crumb:** the spec-versus-shipped note **How it goes.** At the end of a project, your student lays the first spec beside the finished program and goes line by line. What did the spec promise that shipped? What shipped that the spec never mentioned? What did the spec promise that didn't ship, and why? They write a short change note. Something that shipped without being in the spec gets a decision: add it to the spec with a reason, or take it out. **17–18:** at the end of every project. This note goes in the portfolio (Chapter 9). ### Here's how one Hour might go (17–18) This is a composite, not a real family. Remember the chore rotation tool from the start of the chapter? Its user stories included "As the youngest sister, I want my chores printed in big letters, so that I can read them myself." The acceptance line: "Given four names and seven days, every name appears at least once." At the end of the week, the spec diff turned something up. The tool now skipped anyone marked "away," which no spec line had ever mentioned. He'd added it on Thursday, when a sister went to a sleepover. His first instinct was to delete it, because it wasn't in the spec. Instead he added it to the spec, with a date and a reason ("added after a real absence; needed for fairness"), and wrote a new example. His exit line: "I specified a rotation for three sisters. I predicted the spec diff would be clean. It wasn't: I'd added absences. Next I'd change the printout to show who was away. Help I used: none." ### In-home — ALG-01 Two Ways to Search - **Time:** 20 minutes - **Materials:** 32 index cards numbered 1 to 32 (or playing cards), a tally sheet - **Safety and privacy:** none needed - **The fun:** a race between two methods, with a clear winner and a catch - **The skill:** linear versus binary search with cards; counting steps as the list doubles - **The crumb:** the step-count table **How it goes.** Use sixteen cards first. Shuffle them and lay them face down in a row. You choose a target number. Your student finds it by flipping cards one at a time from the left, and you tally the flips. That's linear search. Do it three times and write down each count. Now sort the cards and lay them face down in order. Your student flips the middle card. If it's too high, the target must be to the left, so the whole right half goes away. Flip the middle of what's left. Keep halving. That's binary search. Tally again. Before using all 32 cards, your student predicts both new counts in writing. Then they run both searches and compare. With sixteen cards, linear search can take up to sixteen flips, and binary search never more than five. With thirty-two, linear can take up to thirty-two, and binary never more than six. Doubling the cards doubles one count and adds one to the other. The catch: binary search only works on sorted cards. Ask, "What did we have to do first, and did that cost anything?" **15–16:** sixteen cards, then thirty-two with a prediction. **17–18:** add a column to the table for "64 cards (predicted)" and have your student explain the pattern in one sentence. Here's the same idea in Python, for later in the year. Your student doesn't need to understand every line yet; the point is that the counts match the cards. ```python def linear_steps(cards, target): steps = 0 for card in cards: steps += 1 if card == target: return steps return steps cards = list(range(1, 17)) print(linear_steps(cards, 16)) ``` This prints `16`, the worst case for sixteen cards. With `range(1, 33)` and a target of 32, it prints `32`. ### In-home — ALG-02 Sort by Hand, Count the Work - **Time:** 25 minutes - **Materials:** ten playing cards, a tally sheet - **Safety and privacy:** none needed - **The fun:** discovering that "just sort them" hides a lot of work - **The skill:** selection sort and merge sort with playing cards; comparisons tallied - **The crumb:** the comparison tally **How it goes.** Deal ten cards face up in a row. First, selection sort: your student scans the whole row for the smallest card, moves it to a new row, and repeats. You make a tally mark every time they compare two cards. Then shuffle and try merge sort: split the row into pairs and sort each pair, merge pairs into fours, merge fours into eights, and so on, comparing only the front cards of the two piles being merged. Tally again. Compare the two tallies. With ten cards the difference is noticeable; ask your student to predict what happens with a hundred. **15–16:** selection sort first, merge sort on a second day. **17–18:** both in one session, and a written sentence on which they'd choose for a thousand cards and why. ### In-home — ALG-03 Pseudocode to Trace Table - **Time:** 15 minutes - **Materials:** a short program on paper, a ruled sheet - **Safety and privacy:** none needed - **The fun:** being the computer - **The skill:** tracing a loop with an accumulator line by line before running it - **The crumb:** the trace table **How it goes.** Give your student this program on paper: ```python total = 0 for n in [3, 5, 2]: total = total + n print(n, total) print("done", total) ``` They draw a table with a column for each name that changes (`n` and `total`) and a column for what gets printed. Then they go one line at a time, writing each new value in a new row. When they're finished, they write their predicted output at the bottom and only then run it. It prints: ``` 3 3 5 8 2 10 done 10 ``` If the trace and the run disagree, the disagreement is the lesson. Find the row where they part ways. **15–16:** loops with one accumulator, like this one. **17–18:** loops with an `if` inside, or two accumulators. Chapter 2 picks this card up again with real files. ### In-home — ALG-04 Coin Flip or Rule? - **Time:** 15 minutes - **Materials:** a die, eight index cards describing procedures - **Safety and privacy:** none needed - **The fun:** proving something changes by doing it three times - **The skill:** deterministic versus probabilistic algorithms with dice and a fixed rule - **The crumb:** the two-column sort of examples **How it goes.** On each card, write a procedure: a recipe, a shuffled playlist, a dice game, alphabetizing a shelf, a coin toss to pick who goes first, a bus timetable, a sorting rule, a "random fact of the day." Your student sorts them into two columns: "same input, same output every time" and "might change." Then they pick one card from the second column and run it three times to prove it. Ask: "Is a weather forecast in the first column or the second? What about a chatbot's answer?" Chapter 8 comes back to that last one. **17–18:** the full card set. **Ready 16:** fine for any sixteen-year-old who has done ALG-01 and ALG-03. ### In-home — PLAN-03 Scope It Down - **Time:** 15 minutes - **Materials:** a project idea that's too big, two columns on paper - **Safety and privacy:** none needed - **The fun:** keeping the dream and shipping something real - **The skill:** cutting a too-big project idea to a version that can ship in two weeks - **The crumb:** the before-and-after scope list **How it goes.** Every student eventually proposes a project the size of a small company: a game with online multiplayer, a social network for the co-op, an app that does everything. Don't say no. Say, "What's the version you could finish in two weeks?" Your student writes every feature on the left, then moves only the ones that a first user truly needs to the right. The right column becomes the spec. The left column stays on file as "later," and some of it will come back. ### Out-of-home — OUT-01 Algorithms in Public - **Time:** 20 minutes, plus travel - **Materials:** a notebook, a pencil - **Safety and privacy:** observe, don't film; no photos of strangers or their screens - **The fun:** spying on a machine's rules in plain sight - **The skill:** writing a spec for a self-checkout, an elevator, or a traffic signal from observation - **The crumb:** the spec page **How it goes.** Pick a machine with rules: a self-checkout, an elevator bank, a crosswalk signal, a parking-garage gate. Your student watches for ten minutes and writes down everything it does, especially what happens when something unusual occurs. Back home, they turn their notes into a one-page spec in the SPEC-01 format, as if they were the engineer who had to build it. Their edge-case example must be something they actually saw: the elevator that skipped a floor, the self-checkout that called for an attendant. **15–16:** you go together, and you compare notes on the way home. **17–18:** your student goes alone, and adds two user stories for different users of the same machine (a person with a full cart, a person using a wheelchair). ### Talk box (this chapter) **Opening:** "What exactly should it do — and how will you know it's done?" **Follow-ups:** 1. **Prediction:** "If I followed this spec exactly, where would I get stuck first?" 2. **Evidence:** "Which example in your table shows that rule?" 3. **Location:** "Which line of the spec says what happens when the input is empty?" 4. **Change:** "If you could add one more example, which would it be?" 5. **Revision:** "You can change the done line. Does it still say what you mean?" **How to wait.** Count to five in your head. When the question is about code on the screen, let them read as long as they need. Look at the code, not at the student. **What a stuck silence usually means.** In this chapter, usually that there's no done line yet, so there's nothing to check the question against. Or the question was about code when the spec is about behavior. Try again with "What will the person using it see?" **Don't say / say instead.** Don't say "That spec is too vague"; say "Read me the line that tells me when I'm finished." ### One wrong example to diagnose Give your student this spec and ask what's wrong with it. Don't hint. > **Purpose:** A program that helps with homework. > **User:** Students. > **Inputs:** The homework. > **Outputs:** Help. > **Rules:** It should be good. > **Examples:** If I put in my math homework, it helps me. There's no done line, so nobody could ever say it's finished. The user is everyone, which means it's built for no one. Every heading is filled in, and nothing is specified. A good repair starts by picking one student, one subject, and one kind of help, and ends with a line a stranger could check. ### Working with a partner Siblings, co-op classes, and two students sharing one computer can work as a pair. Pair programming is a simple arrangement: one person types (the driver) while the other reads, questions, and spots problems (the navigator), and they swap roles every ten or fifteen minutes. A review of studies of pair programming in programming courses found positive results for pairs on programming assignments, exams, and passing rates, though not on students' attitudes.^[11](#note-11)^ Most of those studies were college classes, not homes, so treat it as promising, not proven for your family. For pairing at home, a few rules help. Each pair writes one spec together. Swap roles on a timer. The navigator never grabs the keyboard; they point with words, just as you do. Both say the exit line, and both write their own "Help I used: …" At 17–18, two students can also spec together and build separately, then compare results; Chapter 9 counts both. ## For the student This section is for you. Your parent may read it too, but it's written to you. At this age, computing changes. Up to now, someone else probably decided what you'd build. A lesson, a tutorial, or a course told you what to make, and your job was to make it. From here on, the work is yours. You decide what to build. You write down what it must do. You run the session. Your parent's job becomes asking hard questions, using your program like a stranger, and signing your records. Your job is to make something real and be able to explain every part of it. The first tool for that is the spec. ### What a spec is A spec is a short written description of what a program must do, with examples and a line saying what "done" means. You write it before you write any code. It's not homework about your homework. It's the cheapest place to find your mistakes. A wrong idea costs you a minute to cross out on paper and an afternoon to unpick in code. A good spec has six parts: purpose, user, inputs, outputs, rules, and a done line. It also has examples, at least one of them odd. Here is a tiny one: > **Purpose:** Tell me how many minutes I've practiced guitar this week. > **User:** Me, every evening. > **Inputs:** A minutes number each day, typed in. > **Outputs:** The week's total and the daily average, as whole numbers. > **Rules:** Negative numbers aren't allowed. A day I skip counts as zero. > **Examples:** 30, 20, 0, 45, 30, 0, 25 → total 150, average 21. Seven zeros → total 0, average 0. Someone types "-10" → it says "minutes can't be negative" and asks again. > **Done when:** all three examples work and my brother can use it without asking me anything. Notice what it doesn't say. It doesn't say "use a loop" or "store it in a list." Those are decisions about code, and you'll make them later. A spec is about what the person using it sees. ### Why it's worth it Professionals write specs because guessing is expensive. When you sit down to code with a spec, you know exactly what you're aiming at, and you know when to stop. When something goes wrong, you can check the program against the examples instead of arguing with yourself about what it should do. And when your parent, or a college instructor, or a future employer asks what you built, you can show them. ### Algorithms are the steps inside Once you know what the program must do, you need the exact steps to do it. That's an algorithm. Some algorithms are faster than others, and you can measure the difference by counting steps. This week you'll search a stack of cards two ways and find out that one method takes up to thirty-two flips for thirty-two cards while the other never takes more than six. That's a real difference, and it gets bigger the more data you have. ### One to write today Write a one-page spec for something you'd actually use this month. A homework timer. A tool that splits a pizza order among friends. A tracker for the books you're reading. Use the six parts. Include three examples, and make one of them strange. Sign it and date it. Then hand it to your parent and ask them to find the weakest line. Fix it in a different color. ### Explain it back When you're done, try this without looking: tell your parent, in three sentences, what your program does, who it's for, and how you'll know it's finished. If you can't, the spec isn't done yet. ### This part is hard for everyone Edge cases. Nearly everyone writes examples that are all ordinary, because you imagine yourself using the program, and you know what to type. Real users don't. They type words where numbers go, press Enter on an empty box, or paste in a whole paragraph. Every time you write a spec, ask yourself: "What would a stranger type?" Then write that down as an example. ### A challenge Go to a store with a self-checkout and watch it for ten minutes. (Don't film anyone.) Pay attention to what it does when someone puts something in the bagging area that it didn't expect. Write the spec for that one rule, the "unexpected item" rule, as if you were the engineer who had to build it. What are the inputs? What does it do? What should it do when a customer puts down their own bag? How would you know your version was done? You'll find that a rule that annoys millions of people every day is a genuinely hard problem. ## If it isn't clicking | What you see | What it usually means | Next move | |---|---|---| | Specs that describe code ("use a for loop") | Behavior and method are mixed up | Rewrite each line as "what a user sees"; run SPEC-03 again | | No edge-case example, ever | Hasn't imagined a careless or hostile user yet | Ask, "What would a stranger type?"; try the boundary hunt in Chapter 3 early | | Step counts guessed, not counted | Algorithms still feel abstract | Cards on the table; ALG-01 again with all 32 cards | | The spec is three pages long | Spec as homework, not as a tool | PLAN-03: what's the two-week version? One page only | When your student is stuck in the moment, use the rescue order: ask → wait → hint → short demo on your own copy → hand it back. The demo, in this chapter, is usually you writing a spec of your own on a separate sheet, then putting it away. If specs keep feeling pointless, that's a sign the projects are too small for a spec to matter. Pick something that someone else will use. A grandparent, a younger sibling, or a co-op teacher makes a spec feel necessary very quickly. If you'd like outside help, a working programmer will talk about specs for twenty minutes without much prompting. Chapter 6 has an activity for that. ## Tools, including AI This chapter needs paper, pencils, index cards, and a deck of playing cards. A screen is optional until the Python version of ALG-01, which any Python editor can run. Chapter 2 sets that up. The AI box in **The Computing Hour** covers what AI may and may not do. One point applies here especially. A chatbot can generate a spec in seconds, and it will look good. It won't be your student's spec. It won't know who the user is or what "done" means in your house, and writing the spec is where your student learns what they're building. Specs in this chapter are written by hand, without AI. Check the current terms before using any service. ## What "done enough" looks like Your student is ready to move on when they can: - [ ] write a one-page spec with all six parts, a done line, and at least one edge-case example (SPEC-01, SPEC-02); - [ ] repair a spec after a literal reader stalls on it (SPEC-03); - [ ] count the steps for linear and binary search with cards, and predict what happens when the stack doubles (ALG-01); - [ ] trace a short loop on paper and get the output right before running it (ALG-03); - [ ] sort procedures into "same every time" and "might change" (ALG-04, 17–18 or ready 16); - [ ] write a spec from something observed out in the world (OUT-01); - [ ] **AS-01 Cold Trace, baseline:** trace a short program alone, without AI or notes, and predict its output; dated and filed. At 17–18, add: user stories with acceptance lines for one project (SPEC-04), and a spec diff at the end of it (SPEC-05). The Cold Trace (AS-01) is a baseline, not a grade. Repeat it once a month. A student who comes into this book already writing clean specs and tracing loops easily can move fast through this chapter and start Chapter 2 in week two. A student who finds all of it new should take two or three weeks here. Place by skill, not birthday. \newpage # Chapter 2 ## Python as a Tool: Programs That Read, Compute, and Write ![An open laptop whose dark screen shows rows of indented colored bars, beside a printed data file with columns and a mug — still life, no people, no logos, no readable text.](art/ch02-opener.jpg){width=100%} ## Why this matters Here is a picture. It is an illustration, not a real family. A fifteen-year-old keeps a reading log in a plain text file, one line per book: the title, a comma, and the number of pages. Her spec says the program should read the file and print the total pages for the year. Her prediction, written in the Debug Log before the first run: "817." The first run crashes. The red text ends with a line that names a `ValueError`. She reads that last line first, the way **The Computing Hour** taught her, and then the line number above it. The problem is the last line of her file, which is empty. An empty line has no comma, so it can't be split into a title and a page count. She adds two lines of code to skip empty lines, runs it again, and gets 817. Then she notices something else. One of her lines says `312 ` with a space after the number, and that one worked fine. She'd expected it to crash too. She checks, and it turns out Python's `int()` quietly ignores spaces around a number. She writes it in the log as a good surprise: "`int` forgives spaces. It does not forgive empty." That is Python at this age. In *Computing for Young Minds*, Python was a first language: printing, asking, looping, and drawing. Here it becomes a tool. Real programs read something, compute something useful, and write a result a person can use. They work with real files, real data, and the libraries that come with the language. And they break in ways that teach you something, if you read the red text. Python is a good working tool and the most common first text language, which is why this book uses it for most of the year. It isn't "the best language"; there's no such thing, only good fits. Your student will meet Java in Chapter 4, SQL in Chapter 5, and the languages of the web in Chapter 6. Python is the one they'll reach for when they need to get something done. ## For the parent: understand it yourself ### The plain picture A Python program is a text file of instructions that the computer follows from top to bottom. Most useful programs do three things: they **read** (from a file, or from what someone types), they **compute** (add up, count, sort, compare), and they **write** (print to the screen, or save a new file). This chapter is built around that shape. Programs are made of a few kinds of things: - **Values** of different **types** (what kind of value something is): whole numbers like `312`, text like `"Salt Road"`, lists like `[195, 312, 310]`. - **Names** that hold values: `total = 0`. - **Functions**, named chunks of code you can use again. A function can hand back a **return value**, which is what it gives to the code that called it. - **Libraries**, collections of ready-made functions. Python comes with a large standard library, and part of being a programmer is knowing how to find what's in it. ### The precise picture Here are the ideas that trip up nearly every student at this stage. You don't need to fix them; you need to recognize them. **Text that looks like a number isn't a number.** Anything read from a file or typed by a user arrives as text. `"7" + "3"` is `"73"`, because adding text joins it. `int("7") + int("3")` is `10`. Python's `int()` turns text into a whole number, and it's forgiving about spaces around the digits: `int("7 ")` gives `7`. It isn't forgiving about anything else. `int("7.5")` and `int("")` both stop the program with a `ValueError`. **`print` and `return` are different jobs.** `print` shows something on the screen for a person. `return` hands a value back to the code that called the function. A function that prints its answer instead of returning it looks like it works, until another part of the program tries to use the answer and gets `None`, which is Python's word for "nothing." **`range` stops one short.** `range(1, 5)` gives 1, 2, 3, and 4, not 5. This is deliberate, and it causes more off-by-one errors than any other line in Python. **Where the program runs matters.** When a program opens `"reading_log.txt"`, Python looks for that file in the folder the program is running from, which isn't always the folder you think. "The file doesn't work" usually means "Python is looking in the wrong place." **Lists and dictionaries do different jobs.** A list keeps things in order: `["Salt Road", "Winter Fox"]`. A dictionary looks things up by a key: `{"tacos": 3, "pizza": 2}`. Counting how many times each thing appears is a dictionary job. Keeping a ranking is a list job. The high-school standards many schools use put the library skill plainly: students should "Use documentation, libraries, application programming interfaces (APIs), and other tools in program development."^[12](#note-12)^ Reading the documentation is not a fallback for when you're stuck. It's part of the work, and it's a skill you can teach without knowing the answer yourself. ### Wrong answers you should be able to hear - **"It printed the right number, so the function works."** Possibly `print` where `return` was needed. Ask: "If another function used this answer, what would it get?" - **"It says 73 instead of 10."** Text treated as a number. Ask: "What type is that value when it comes in?" - **"It skipped the last one."** Probably `range`. Ask: "Read me the range line. What's the last number it gives?" - **"The file is empty"** or **"the file doesn't work."** Usually a path problem. Ask: "Which folder is the program running from? Print it." - **"It removed some of them but not all."** Changing a list while looping over it. Ask: "What happens to the next item when you remove this one?" ### A five-minute warm-up for you On a sheet of paper, predict what each line prints. Then ask your student to run them and check you. ```python print("7" + "3") print(int("7") + int("3")) print(int("7 ")) ``` The answers are `73`, `10`, and `7`. If the third one surprised you, you're in good company, and you've just learned the most useful habit in this chapter: predict, then check. ## How to teach it this week ### Setting up If your student is new to typed code, start with Thonny, a free Python editor built for learners. It runs offline, needs no account, and comes with Python included, so there's one thing to install.^[13](#note-13)^ It also lets you run a program one step at a time and watch each name change, which makes tracing visible. If your student has used Python before, any editor that runs Python works; Chapter 6 introduces a general-purpose editor and the terminal. CodeAI (formerly Code.org) also offers a browser-based Python Lab designed for students aged 13 and up, which suits a library Hour.^[14](#note-14)^ Make one folder for this chapter, inside the course folder, and keep every program and every data file for the chapter in it. Many path problems disappear when everything lives together. ### The session shape Here's a Computing Hour for a "read, compute, write" day. **Specify.** Your student writes or updates the spec: what file goes in, what comes out, three examples (one of them an empty or odd file), and the done line. **Predict.** Before each run, a written line: "I predict it will print 817." Use PY-02 (below) at the start of the Hour if your student needs a warm-up. **Build and Test.** Small steps. First, a program that just opens the file and prints each line. Run it. Then split each line. Run it. Then add up. Run it. Each run gets checked against the spec's examples. **Debug and Log.** When red text appears, try this exact sentence: "Read me the last line. What's the error's name? Which line?" Then wait. Your student writes Expected/Actual and a guess before changing anything. **Review.** Your student rereads the program against the spec and saves it with a message: "Skip blank lines in the reading log." **Ship and Explain.** "I specified… I predicted… It did… Next I'd change…" and "Help I used: …" ### In-home — PY-02 Predict the Output - **Time:** 10 minutes - **Materials:** three to five short programs on paper or on screen, a prediction sheet - **Safety and privacy:** none needed - **The fun:** betting against Python and sometimes winning - **The skill:** a written prediction of a short program's output, then run and compare - **The crumb:** the prediction-and-result lines **How it goes.** Show your student a short program. They write, on paper, exactly what it will print, line for line. Then they run it and write what it actually printed beside the prediction. For each mismatch, they write one sentence: "I thought ___ but Python ___." Use the three lines from your warm-up, then the `print`/`return` program below, then a `range` loop. Make a habit of it: five minutes at the start of any Hour. **15–16:** one program at a time; you choose them. **17–18:** your student writes predict-the-output puzzles for you, and has to know the answer first. ### In-home — PY-01 A Program That Reads a File - **Time:** 30 minutes - **Materials:** a computer with Python, a small text file your student makes - **Safety and privacy:** use made-up or family-only data; no one else's names - **The fun:** a program that does something with your own information - **The skill:** opening a text file, reading lines, stripping whitespace, and counting - **The crumb:** the program and its sample input file **How it goes.** Your student makes a text file called `reading_log.txt` with a few lines in the form `title, pages`, and leaves an empty line at the end on purpose. Here is a first version of the program, saved in the same folder: ```python total = 0 with open("reading_log.txt") as f: for line in f: title, pages = line.split(",") total = total + int(pages) print("Pages read:", total) ``` With a file of three books (195, 312 with a trailing space, and 310 pages) and a blank last line, this crashes. The last line of the red text reads `ValueError: not enough values to unpack (expected 2, got 1)`, and the line above it points to the `split` line. The blank line split into one piece, not two. Here's the fix: ```python total = 0 with open("reading_log.txt") as f: for line in f: line = line.strip() if line == "": continue title, pages = line.split(",") total = total + int(pages) print("Pages read:", total) ``` This prints `Pages read: 817`. `strip()` removes spaces and the invisible end-of-line character from both ends; `continue` skips to the next line. Notice that the line with `312 ` never caused trouble: `int()` ignored the space. **15–16:** start with the crashing version and let your student find the bug. That's the lesson. **17–18:** start from a blank file and the spec, and add a second output: the longest book. ### Fading your help In the first week, you read the error's last line aloud together. By the third week, your student reads it before you can ask. By the end of the chapter, they're telling you what the error means before they've finished reading it, and they're right more often than not. When that happens, say so in one specific sentence: "You went straight to the last line and found the blank line. That's exactly how it's done." ### Band moves **15–16:** one file in, one result out; Thonny if new; you're first user every session (try a file with a typo in it). **17–18:** read a file, compute, and write a report file; use one standard-library module and its documentation; first user weekly. ## Practice that actually builds learning ### In-home — PY-03 Functions With Return Values - **Time:** 25 minutes - **Materials:** a computer with Python - **Safety and privacy:** none needed - **The fun:** building a tool once and using it everywhere - **The skill:** `def`, parameters, `return`, and a docstring; calling one function from another - **The crumb:** the program file **How it goes.** Start with a predict-the-output on this program: ```python def double_print(n): print(n * 2) def double_return(n): return n * 2 a = double_print(4) b = double_return(4) print(a, b) ``` It prints `8` (from inside `double_print`) and then `None 8`. The first function showed the answer and handed back nothing. The second handed back the answer, so `b` holds it. Then your student writes two small functions of their own, each with a one-line docstring (a short description in triple quotes, just under the `def`), and one function that calls the other: ```python def average(numbers): """Return the mean of a list of numbers.""" return sum(numbers) / len(numbers) def describe(numbers): """Return a one-line summary.""" return f"{len(numbers)} items, average {average(numbers):.1f}" print(describe([195, 312, 310])) ``` This prints `3 items, average 272.3`. Ask, "What happens if the list is empty?" and let them try it. (`average([])` stops with a `ZeroDivisionError`, which is a fine edge case for the spec.) ### In-home — PY-04 Write a Report File - **Time:** 30 minutes - **Materials:** a computer with Python, a text file with some words in it - **Safety and privacy:** use your own writing or a passage you made up - **The fun:** a program that leaves something behind for a person to read - **The skill:** computing totals and writing a formatted report to a new file - **The crumb:** the report output file **How it goes.** This program counts the words in a file and writes the five most common to a new file called `report.txt`: ```python counts = {} with open("story.txt") as f: for line in f: for word in line.lower().split(): counts[word] = counts.get(word, 0) + 1 top = sorted(counts.items(), key=lambda pair: pair[1], reverse=True)[:5] with open("report.txt", "w") as out: for word, n in top: out.write(f"{word}: {n}\n") print("Wrote", len(top), "lines") ``` With a `story.txt` of three short lines ("the cat sat on the mat," "the dog sat on the log," "A cat and a dog"), it prints `Wrote 5 lines`, and `report.txt` begins `the: 4`. Several words tie at 2, and the order of tied words depends on which came first in the file, which is a good conversation about what "top five" means when there's a tie. Ask your student to open `report.txt` and check it by hand against the story. The `"w"` means "write," and it replaces any old file with the same name, so a spec line about that is worth adding. **15–16:** run it, predict the report, then change it to the top three. **17–18:** add a rule to the spec (ignore words shorter than three letters) and build it. ### In-home — PY-05 Use a Library, Read Its Docs - **Time:** 25 minutes - **Materials:** a computer with Python and internet access, or the documentation saved for offline use - **Safety and privacy:** official documentation only; no downloads from unknown sites - **The fun:** finding a tool someone already built - **The skill:** importing a standard-library module (csv, random, datetime) and finding the answer in the documentation - **The crumb:** a docs note with the line that answered it **How it goes.** Give your student a question that a standard-library module answers, and have them find the answer in Python's official documentation, not a search result or a chatbot.^[15](#note-15)^ Good questions: "How many days since we started school this year?" (the `datetime` module), "Pick a random chore from a list" (`random`), "Add up the minutes column in a spreadsheet file" (`csv`). Here's a `datetime` answer: ```python from datetime import date start = date(2026, 9, 8) today = date(2026, 10, 12) print((today - start).days, "days since we started") ``` This prints `34 days since we started`. The crumb is a short note: the question, the page of the documentation, and the exact sentence on that page that answered it. At first this will feel slower than asking someone. Within a month, it will be faster, and it's the skill that lasts. ### In-home — PY-06 Paper Parsons, Python Edition - **Time:** 10 minutes - **Materials:** a working function printed out and cut into strips, plus one extra strip - **Safety and privacy:** keep scissors for the parent at 15 if you like; otherwise none - **The fun:** a puzzle with exactly one right answer and one trap - **The skill:** reordering cut-up Python lines into a working function - **The crumb:** the taped strip **How it goes.** Print this function, cut it into one strip per line, and add one distractor strip such as ` return word` indented inside the `if`: ```python def longest_word(words): best = "" for word in words: if len(word) > len(best): best = word return best print(longest_word(["map", "lantern", "fox"])) ``` Your student puts the strips in order, including the indentation, explains in one sentence why the distractor doesn't belong (it would hand back the first word longer than nothing, which is the first word, and stop), and tapes the result down. Then they run the real thing. It prints `lantern`. Paper Parsons is the best first move for a student who freezes at a blank file. Chapter 4 brings it back in Java. ### In-home — DS-01 Lists, Dictionaries, and When - **Time:** 15 minutes - **Materials:** six task cards, a computer for the second half - **Safety and privacy:** none needed - **The fun:** arguing for a choice - **The skill:** choosing a list or a dictionary for a job and saying why - **The crumb:** the choice card with reasons **How it goes.** On each card, write a job: "the order people finished a race," "how many times each word appears," "a phone list where you look up a name," "the next five chores in order," "each student's favorite color," "the high scores, best first." Your student sorts them into "list" and "dictionary" and writes one reason for each. Then they build one of each in Python and print it. Some cards have two defensible answers, and the reason is what counts. ### In-home — DS-02 Dictionary Counter - **Time:** 25 minutes - **Materials:** a computer with Python - **Safety and privacy:** use made-up votes or family-only choices - **The fun:** settling a family argument with data - **The skill:** counting words or items with a dictionary, and sorting the result - **The crumb:** the program file **How it goes.** Take a family vote on something low-stakes, such as dinner, and type the votes into a list: ```python votes = ["tacos", "pizza", "tacos", "soup", "tacos", "pizza"] counts = {} for v in votes: counts[v] = counts.get(v, 0) + 1 print(counts) for food, n in sorted(counts.items(), key=lambda p: p[1], reverse=True): print(food, n) ``` This prints `{'tacos': 3, 'pizza': 2, 'soup': 1}`, then `tacos 3`, `pizza 2`, and `soup 1` on separate lines. Ask your student to explain `counts.get(v, 0)` out loud, which is the heart of it: "Look up this food; if it isn't there yet, start at zero." Then change the program to read the votes from a file instead. ### In-home — DS-03 Nested Data on Paper - **Time:** 15 minutes - **Materials:** paper, colored pencils - **Safety and privacy:** none needed - **The fun:** drawing a map of data - **The skill:** drawing a list of dictionaries (records) and tracing access paths - **The crumb:** the diagram **How it goes.** Real data often comes as a list of records, where each record is a dictionary: ```python books = [ {"title": "Salt Road", "pages": 195, "tags": ["travel", "history"]}, {"title": "Winter Fox", "pages": 310, "tags": ["animals"]}, ] print(books[1]["title"]) print(books[0]["tags"][1]) print(len(books[0]["tags"])) ``` Your student draws it first: a long box for the list, two boxes inside for the dictionaries, labeled arrows for each key. Then they trace each `print` line along the arrows and predict: `Winter Fox`, `history`, `2`. Then they run it. Chapter 5 uses this exact shape for data. **17–18:** draw it, then write three access paths of your own for your parent to trace. **Ready 16:** for any sixteen-year-old comfortable with lists and dictionaries. ### Back to the trace table ALG-03 from Chapter 1 comes back here with real programs. Before running any new loop in this chapter, especially one that reads a file, your student traces the first three times around the loop on paper. It takes two minutes, and it catches the blank-line bug before it happens. ### Out-of-home — OUT-02 Library Computer Hour - **Time:** about 50 minutes - **Materials:** a library card, a USB stick or family cloud folder, today's spec on paper - **Safety and privacy:** log out of everything; save nothing to the library computer - **The fun:** proving the program runs on a computer that isn't yours - **The skill:** a Computing Hour on a public computer; logging out; saving to your own drive - **The crumb:** the file saved in two places **How it goes.** This try-it is described in **The Computing Hour**; here it gets a Python job. Your student brings a spec for a small "read, compute, write" program and the data file on a USB stick, and builds it on the library computer in a browser-based Python editor, such as CodeAI's Python Lab, if the library allows it. Files in browser editors sometimes behave differently from files on your own computer, which is its own good lesson about paths. At the end: save to the stick, check it opened, log out, close the browser. **15–16:** you go together. **17–18:** alone, with a text to you when the file is saved in two places. ### Talk box (this chapter) **Opening:** "What goes in, what comes out — and what will this line do to it?" **Follow-ups:** 1. **Prediction:** "What will `total` be after the second time around the loop?" 2. **Evidence:** "What did the last line of the red text say, exactly?" 3. **Location:** "Which line is the last one that did what you expected?" 4. **Change:** "What's the one line you'd change, and what do you predict will happen?" 5. **Revision:** "You can change your prediction. Run it again." **How to wait.** Count to five in your head. When the question is about code on the screen, let them read as long as they need. Look at the code, not at the student. **What a stuck silence usually means.** In this chapter, it's often that your student is reading the error from the top, where it's least useful. Point gently: "Start with the last line." Or there's no written prediction, so there's nothing to compare. Ask for one before the next run. **Don't say / say instead.** Don't say "You forgot to convert it"; say "What type is that value when it comes in from the file?" ### One wrong example to diagnose Show your student this program and its output, and ask what's wrong. ```python scores = [4, 7, 7, 2] for s in scores: if s == 7: scores.remove(s) print(scores) ``` It's supposed to remove every 7. It prints `[4, 7, 2]`. One 7 survived. When the loop removed the first 7, everything after it shifted left by one, and the loop moved on to the next position, skipping the second 7 entirely. The lesson isn't this particular bug; it's the rule behind it: don't change a list while you're looping over it. Build a new list instead. Ask your student to write the fix and prove it with a list that has three 7s in a row. ### Blocked, then mixed For the first two weeks, practice one card type at a time: a week of file reading (PY-01, PY-04), a week of functions (PY-03, PY-06). Then mix. Each Hour starts with a two-minute predict-the-output on something from a different card than the day's main work. Mixing feels harder, and that's the point; your student is learning to choose the tool, not just use the one in front of them. ## For the student This section is for you. In this chapter, Python stops being something you're learning and becomes something you use. The test of a tool is whether it does a job you care about. So let's start with one. ### Reading a file Most useful programs start by reading something. A file is just text stored on your computer, and Python can open it, go through it one line at a time, and do something with each line. Here's the shape: ```python with open("reading_log.txt") as f: for line in f: print(line.strip()) ``` `open` finds the file. `with` makes sure it gets closed when you're done. The `for` loop hands you one line at a time. `strip()` removes the spaces and the invisible end-of-line character from each end. Every file program you write this year will start something like this. ### A worked example Say your reading log has three books and a blank line at the end. You want the total pages. Your spec says "Done when it prints the correct total for my real file and doesn't crash on a blank line." You predict 817. You run the first version, and it crashes. The red text is called a traceback (Python's report of where an error happened). Read it from the bottom up. The last line names the error and gives a short explanation. The line above it shows you which line of your code was running. Here, it says `ValueError: not enough values to unpack (expected 2, got 1)`, and it points at the line that splits on the comma. Expected two pieces; got one. A blank line has no comma. That's the bug. Write it in your Debug Log before you change anything: "Expected 817. Actual: ValueError at the split line. Guess: the blank line. Try: skip empty lines." Then change one thing. Run it. 817. ### One program to write today Write a reading-log totaler for your own reading, or a practice-minutes totaler, or anything with "name, number" on each line. Write the spec first, with three examples: an ordinary file, a file with a blank line, and an empty file. Predict the output before every run. When it works, add one more feature from your own list: the longest book, the average, or a report written to a new file. ### Explain it back When it works, cover the screen and explain each line to your parent, out loud, in order. Anything you can't explain, look up in the documentation until you can. That's not a test you can fail. It's how the program becomes yours. ### This part is hard for everyone Paths and file names. You will, at some point this year, be completely certain the file is there, and Python will tell you it isn't. You'll see `FileNotFoundError`. Almost always, the program is running from a different folder than the one the file is in. Keep the program and its files in the same folder. If it still fails, add `import os` and `print(os.getcwd())` at the top. That prints the folder Python is looking in. You'll often find the answer in one line. Also: text from a file is always text. If you read `"312"` and want a number, you need `int()`. It'll forgive spaces around the number. It won't forgive an empty string or a decimal point. ### Read the documentation When you need to know how something works, try Python's official documentation before anything else. It's free, it's correct, and it's written for programmers. At first it'll feel dense. Look for the examples near the top of each section. Write down the sentence that answered your question. A month from now, you'll be faster at this than at asking anyone. ### A challenge Write a program that reads any text file and builds a dictionary of word counts, then writes the ten most common words to a report file, ignoring capital letters. Spec it first. What counts as a word? Is "dog," with a comma, the same as "dog"? What should happen with ties? Decide, write it in the spec, and build to it. When you're done, run it on something you wrote and find out which word you use most. ## If it isn't clicking | What you see | What it usually means | Next move | |---|---|---| | `print` where `return` was needed | Output and value are mixed up | Trace two calls on paper; PY-03 with a check that uses the return value | | "The file doesn't work" | The path or working folder is wrong | Print the folder with `os.getcwd()`; keep program and data together; Chapter 6 draws the folder tree on paper | | Can't start from a blank file | Reading has outpaced writing | Paper Parsons (PY-06), then modify a working program before writing one fresh | | Reads the traceback from the top | The habit hasn't formed yet | Cover everything but the last line; read it aloud first, every time | When your student is stuck in the moment, use the rescue order: ask → wait → hint → short demo on your own copy → hand it back. In this chapter, the best hint is usually "Read me the last line of the red text." The demo, if you need one, is a three-line program on your own file that shows the same idea, closed before you hand back the turn. If Python itself isn't clicking after several weeks, slow down rather than speed up. Spend a week on predict-the-output and Paper Parsons only. Reading code fluently comes before writing it fluently, for everyone. If you'd like outside help, a co-op class or a tutor for one session is ordinary; professionals learn from each other all the time. ## Tools, including AI **Editors.** Thonny for students new to text code; any Python editor after that. A browser-based editor, such as the Python Lab from CodeAI (formerly Code.org), for library Hours. The book never names a Python version; any current one works. **Documentation.** Python's official documentation is free and is the first place to look. **AI.** The AI box in **The Computing Hour** sets the rules. What's specific here: at 15–16, after your student has written Expected/Actual and a guess, a chatbot may explain a traceback or an idea. Ask it to explain, not to fix. The editor assistant stays off through 16, and AI is off for every check. Because the documentation is the skill this chapter teaches, have your student check anything a chatbot tells them about Python against the documentation. If they disagree, the documentation wins. Check the current terms before using any service. ## What "done enough" looks like Your student is ready to move on when they can: - [ ] write a program that reads a file, computes something, and prints or writes a result, built to their own spec (PY-01, PY-04); - [ ] predict the output of a short program in writing and explain any mismatch (PY-02); - [ ] write a function that returns a value, with a docstring, and explain the difference between `print` and `return` (PY-03); - [ ] find an answer in Python's documentation and write down the sentence that answered it (PY-05); - [ ] reorder a cut-up function correctly (PY-06); - [ ] choose a list or a dictionary for a job and say why, and count with a dictionary on purpose (DS-01, DS-02); - [ ] run a Computing Hour on a library computer and leave the file in two places (OUT-02); - [ ] **AS-01 Cold Trace:** this month's, alone, dated; - [ ] **AS-03 Explain Your Code:** explain one of their own programs line by line to you, without notes or AI. At 17–18 (or ready 16), add: draw a list of dictionaries on paper and trace three access paths (DS-03). A student who moves through this chapter quickly and can explain every line is ready for Chapter 3, where tests make all of this provable. A student who's still unsure about files and functions should stay another week or two. Place by skill, not birthday. \newpage # Chapter 3 ## Testing and Debugging: Proof Before Pride ![A test table ruled into four columns with check marks and one red cross, a magnifying glass, a small rubber duck and a pencil — still life, no people, no logos, no readable text.](art/ch03-opener.jpg){width=100%} ## Why this matters Here is an illustration, not a real family. Picture a seventeen-year-old who has written a function that grades a quiz. She has run it four times on four answer sheets she typed herself, and it gave the right percent every time. She is proud of it, and she should be. Then her father sits down as first user, leaves every answer blank, presses Enter, and the screen fills with red text. Her face falls. Thirty seconds ago the program was finished. Now it feels like it was never any good. Nothing about the program changed in those thirty seconds. What changed is the evidence. Four hand-picked inputs proved that the function works on four hand-picked inputs. They didn't prove it does what the spec says, because the spec (if she wrote it the way Chapter 1 taught) promised something about every answer sheet a real user might hand in, including an empty one. This chapter is about the difference between "it ran" and "it's right." A **test** is a check, written down, that compares what the program does with what it should do. A set of tests is written evidence. Debugging is what you do when the evidence says no. The chapter's subtitle is the order of events: proof first, then pride. Pride that comes after proof lasts. Pride that comes before it breaks the first time a stranger types something odd. It is also the third clause of the book's focus line, **Specify it before you build it; predict before you run; debug before you rewrite; explain it before you call it yours.** Chapters 1 and 2 built the first two habits. This one builds the third. A student who meets red text by deleting the file and starting over learns almost nothing from the bug. A student who writes what they expected, reads what happened, makes one guess, changes one thing, and logs it learns something every time, and gets faster every month. There's a feeling side to this, and at 15–18 it's real. Perfectionists hear every failing test as a verdict; quick students change five lines at once because waiting feels like losing; students praised as "good at computers" quietly fear the day the computer proves otherwise. A failing test isn't a grade. It's the bug's address. Your calm is part of the method, and it may be the most important part. Testing is craft, not a learning trick. This book doesn't promise it makes anything else easier, only that your student's programs will do what they say. ## For the parent: understand it yourself You don't need to program to run this chapter. You need to recognize three kinds of error, know how to read the red text in the right order, and be able to ask "What test would prove that?" in a calm voice. All three take about an evening. **The everyday picture.** A recipe card says "bake until done." Two cooks get two different cakes. Now the card says "bake 35 minutes at 350°F; it's done when a toothpick comes out clean." That last line is a test. It's written before anyone bakes, anyone can run it, and it gives the same answer no matter who's holding the toothpick. A test table is a page of toothpicks for a program: for this input, it should give this output. If it doesn't, you know exactly which promise was broken. **The precise picture.** The national high-school standards from the Computer Science Teachers Association describe the goal in one sentence: "Evaluate a computing technology's alignment with design specifications and responsible design values, including its correctness, effectiveness, and user experience."^[16](#note-16)^ Read the middle of that slowly. *Alignment with design specifications.* The spec from Chapter 1 is the measuring stick, and the tests are how you hold the program up against it. A companion standard asks students to evaluate algorithms "for efficiency, correctness, and clarity, using metrics or test cases."^[17](#note-17)^ Test cases are the everyday tool for correctness. ### Three kinds of error Programs go wrong in three ways, and naming them calms everyone down. - A **syntax error** means Python can't read the code at all. A colon or a bracket is missing, so nothing runs. - A **runtime error** means the program starts, reaches a line it can't carry out, and stops with a message. - A **logic error** means it runs, finishes, and gives the wrong answer. No red text. Only a prediction or a test catches it. Here is a syntax error. The colon at the end of the first line is missing: ```python def total(prices) return sum(prices) ``` Python stops before running anything and reports `SyntaxError: expected ':'`, with a small caret under the spot where it gave up. Add the colon and the error goes away. Here is the quiz grader from the opening, with its runtime error. This first version divides by the number of answers the student gave: ```python def score_quiz(answers, key): """Return the percent of answers that match the key.""" right = 0 for given, correct in zip(answers, key): if given == correct: right += 1 return round(100 * right / len(answers)) print(score_quiz(["b", "c", "a"], ["b", "c", "d"])) print(score_quiz([], ["b", "c", "d"])) ``` The first call prints `67`. The second stops the program with a traceback whose last line is `ZeroDivisionError: division by zero`. And here is a logic error, labeled as a deliberate bug because it's the one the boundary hunt below is built to find: ```python def in_band(age): """True for ages 15 to 18, inclusive.""" return 15 < age <= 18 # DELIBERATE BUG: 15 is left out ``` It runs without complaint. `in_band(16)` gives `True`, `in_band(18)` gives `True`, and `in_band(15)` gives `False`, which the docstring says is wrong. Nothing turns red. Only someone who tested the boundary would know. ### How to read a traceback A **traceback** is Python's report of where an error happened, read from the bottom up. Here is the grader's, exactly as it appeared when we ran it (the file path at the top will match your own folder, not ours): ```text Traceback (most recent call last): File "grader.py", line 10, in print(score_quiz([], ["b", "c", "d"])) File "grader.py", line 7, in score_quiz return round(100 * right / len(answers)) ZeroDivisionError: division by zero ``` Recent versions of Python also print rows of little carets and tildes under the part of each line that failed; we've left them out here so the shape is easy to see. Read it in this order: 1. **The last line** says what happened: the error's name (`ZeroDivisionError`) and a message (`division by zero`). 2. **The line just above it** is where it happened: line 7, inside `score_quiz`. 3. **Further up** is how the program got there: line 10 called the function with an empty list. The Python tutorial says this plainly: the last line of the error message indicates what happened, and the place Python reports isn't always the place that needs fixing.^[18](#note-18)^ A missing bracket on one line is often reported on the next. So the habit is: last line, then the line number, then look at that line and the one above it. ### Tests in plain Python Your student doesn't need a testing framework this year. Python has a built-in statement called `assert`: it checks that something is true and stops the program loudly if it isn't. Here's the boundary bug caught by three asserts: ```python assert in_band(16) == True assert in_band(18) == True assert in_band(15) == True, "15 is in the band" print("All tests passed.") ``` The first two pass silently. The third stops the program with `AssertionError: 15 is in the band`, and "All tests passed." never prints. That's a test doing its job: it failed loudly, on the exact promise that was broken. Changing `15 < age` to `15 <= age` makes all three pass and the last line print. At 17–18 (ready 16), the asserts move into their own file, named something like `test_grader.py`, and the student runs that file after every change. Python also ships with a testing framework called `unittest` that does the same with nicer reports; your student may meet it later.^[19](#note-19)^ ### The debugging loop Professional debugging is a short loop, and every step is teachable: 1. **Expected/Actual.** Write it before touching anything: "I expected 0. It crashed." 2. **Read the clue.** The traceback's last line, or the wrong output. 3. **One hypothesis.** "It divides by the number of answers, and there are none." 4. **One change.** Only one. 5. **Run the tests again.** All of them, not just the one you were fixing. 6. **Log it.** One Debug Log entry. The "one change" rule comes from working practice. A well-known book for professional developers notes that if you changed only one thing and the system stopped working, that one thing is likely responsible.^[20](#note-20)^ Change three things and you've learned nothing, even if it now works. **The Debug Log** is the record of that loop. You met it in **The Computing Hour**; this chapter is where it earns its keep. Each entry is dated and holds the symptom, the Expected/Actual line, the hypothesis, the test that checks it, the fix, the lesson, and the minutes spent. The minutes feed the hours log that Chapter 9 turns into credit. **Bisecting.** When a bug hides in a long program, or appeared somewhere in last week's changes, the fastest method is halving. Comment out (or skip) the second half: does the bug still happen? Then it's in the first half. Halve again. Ten halvings narrow a thousand lines to one. At 17–18, the same idea works on history: Chapter 6 shows how Git can jump to the midpoint of a week of commits and ask "good or bad?" **The rubber duck.** Many programmers explain their code, line by line, out loud, to a listener who doesn't need to understand it, even a rubber duck on the desk. It's working practice, not a research finding; the same developers' book says that explaining what the code is supposed to do "often causes the problem to leap off the screen and announce itself."^[20](#note-20)^ You're a very good rubber duck. You just have to listen without fixing. ### Wrong answers you should be able to hear - **"It works on my input."** It ran once, on one example the student chose. Say: "Show me the test that proves it. What about the empty one?" - **"That test is wrong, so I deleted it."** Sometimes a test really is wrong, but usually it's inconvenient. Say: "What did the spec promise for that input? If the spec changed, change the spec first, then the test." - **"I changed a few things and now it works."** No one knows which change mattered. Say: "Which one fixed it? Put the others back and find out." - **"The computer is wrong."** It did exactly what it was told. Say: "Read me the last line of the red text." - **"I'll just rewrite the whole file."** One error has become a reason to throw away an hour of work and the clue with it. Say: "What's in today's Debug Log so far?" ### Your five-minute warm-up Before tomorrow's Hour, type the quiz grader above into the student's editor and run it. Find the last line of the traceback and read it aloud. Then find line 7. Then say this chapter's opening question once, out loud, to an empty room: "What did you expect, what happened instead — and what test would prove the fix?" Practice the silence after it, counting to five in your head. ## How to teach it this week Run the week inside the six steps of **The Computing Hour**. Here's how each step leans toward testing. - **Specify (5–10 minutes).** The spec gets a test table: three or more rows of input and expected output, one of them an edge case. If last week's spec had examples (SPEC-02 Examples Before Code from Chapter 1), they become the first rows. - **Predict (2–5).** "Which of these tests will fail first, and why?" Written. - **Build and Test (15–16: 20–35; 17–18: 30–50).** Code in small steps. Run the tests after every change, not only at the end. - **Debug and Log (5–15).** Expected/Actual, hypothesis, one change, a Debug Log entry. - **Review (5–10).** Read the change against the spec. Did a test get deleted? Did the spec quietly change? Commit test and fix together with a real message (GIT-03 Good Commit Messages, Chapter 6, previews the habit). - **Ship and Explain (3–5).** "I specified… I predicted… It did… Next I'd change…" and "Help I used: …" **Monday: the test table before code.** Start on paper, with no screen at all. ### In-home — TEST-01 Test Table Before Code - **Time:** 15 minutes - **Materials:** the student's current spec, a sheet of paper ruled into four columns (input, expected, actual, pass?), a pencil - **Safety and privacy:** none needed; use made-up data - **The fun:** you get to try to break something before it exists - **The skill:** listing normal, boundary, and bad inputs with expected results, written first - **The crumb:** a test table, dated **How it goes.** The student reads the spec's done line aloud. Then they fill the first two columns: at least two normal inputs, at least one boundary (the smallest, the largest, the empty), and at least one bad input a careless user might type. The "actual" and "pass?" columns stay blank. They're filled in later, on the screen. Try this exact sentence: "Before you write the function, write what it should say for an empty sheet." Then wait. **15–16:** You read the table and ask one question, usually "What would a stranger type here?" Initial it with the spec. **17–18:** The student writes it alone; you read it the same day and add one row they didn't think of. If they can't decide what the right answer *should* be for a row, that's a hole in the spec, not in the table. Send them back to fix the spec. **Tuesday: asserts.** The test table goes into code. ### In-home — TEST-02 Asserts That Fail Loudly - **Time:** 20 minutes - **Materials:** the editor, Monday's test table - **Safety and privacy:** none needed - **The fun:** watching a test catch a mistake you made on purpose - **The skill:** writing an `assert` for each test-table row and reading a failing assert - **The crumb:** a test file, or the asserts at the bottom of the program **How it goes.** One row of the table becomes one `assert` line. The student writes all of them before running anything, then predicts which will fail. Then they break the function on purpose (change `<=` to `<`, say), run again, and read the `AssertionError`. A test that has never been seen failing hasn't been proven to work. **15–16:** asserts at the bottom of the program file are fine. **17–18:** asserts start moving into their own file (TEST-03, below). **Wednesday: the traceback.** Use a program with a real crash, ideally one from the student's own week. ### In-home — BUG-02 Read the Traceback - **Time:** 15 minutes - **Materials:** a printed traceback (or one on screen), an index card, a colored pencil - **Safety and privacy:** none needed - **The fun:** decoding a message that looked scary a minute ago - **The skill:** reading a Python traceback bottom-up: error type, message, file, line - **The crumb:** a traceback decoder card **How it goes.** On the card the student writes four labels: *error type*, *message*, *file and line*, *how we got here*. They circle each one on the printed traceback in a different color, starting from the bottom. Then they say, in one sentence of their own, what Python is complaining about. Only then do they open the file. Keep the card by the keyboard for the rest of the year. **15–16:** do it together the first time, with you reading the last line aloud. **17–18:** the student explains a traceback to you, as if you were a new programmer on their team. **Thursday: the planted bugs.** Someone else plants the bugs. This is where siblings are wonderful. **Friday: first user.** You sit at the keyboard as a stranger (see the try-it below). Then the student turns every surprise into a new test row and makes it pass. **Fading help.** In week one, say "Expected/Actual first" every time; by week three, point at the card; by week five, say nothing. When they reach for the rescue, use the rescue order from **The Computing Hour**: ask → wait → hint → short demo on your own copy → hand it back. A "hint" in this chapter is almost always one of three questions: "What does the last line say?", "Which test fails?", or "What's the smallest input that breaks it?" ## Practice that actually builds learning Practice here has a rhythm: blocked first (one kind of test, one kind of bug, several times), then mixed (a program where the student has to decide what kind of problem they're facing). ### In-home — TEST-04 Boundary Hunt - **Time:** 15 minutes - **Materials:** a spec with a range in it, paper, pencil - **Safety and privacy:** none needed - **The fun:** finding the input the author forgot - **The skill:** finding off-by-one and empty-input boundaries in a spec - **The crumb:** a boundary list **How it goes.** Give the student a one-line spec: "A program says whether a person is in the book's age range, 15 to 18 inclusive." Ask: which inputs matter? A good list has 14, 15, 18, and 19 (each side of each edge); a typical middle value like 16; an empty entry; a word ("sixteen"); and a negative number. Then hand them the deliberately buggy `in_band` function from the parent section and let them find which item on their list catches the bug. (It's 15.) When we ran the corrected version on 14, 15, 18, 19, and −1, it gave `False`, `True`, `True`, `False`, `False`. The word "sixteen" makes it crash with a `TypeError`, because Python won't compare a number and text. That's a second finding: the spec never said what to do with words. Fix the spec first. **15–16:** the parent reads the spec aloud and the student calls out boundaries. **17–18:** the student writes the boundary list for a spec someone else wrote. ### In-home — BUG-03 Planted Bugs Swap - **Time:** 20 minutes - **Materials:** a working copy of a program the student wrote, a second person (parent, sibling, co-op friend) - **Safety and privacy:** always plant bugs in a copy, never the only version - **The fun:** revenge, gently - **The skill:** finding three bugs someone else planted in working code - **The crumb:** a bug list with line numbers **How it goes.** The planter makes a copy of a working program and plants exactly three bugs: one syntax error, one runtime error, and one logic error. (A parent who doesn't code can still do this: delete a colon, change a `len(key)` to `len([])`, change a `<=` to `<`.) The student finds all three, writing an Expected/Actual line and a Debug Log entry for each. The logic bug is always the hardest, which is the whole lesson: the bugs that don't make noise need tests. **15–16:** you plant; they hunt. **17–18:** the student plants bugs for *you*, then coaches you through finding them using the rescue order. ### In-home — BUG-01 Expected/Actual Line - **Time:** 5 minutes, every time something surprises anyone - **Materials:** the Debug Log - **Safety and privacy:** none needed - **The fun:** it turns "ugh" into a sentence - **The skill:** writing what you expected and what happened before touching code - **The crumb:** a Debug Log line **How it goes.** You know this card from **The Computing Hour**. This week it becomes a rule: no keyboard until the Expected/Actual line is written. ### In-home — BUG-05 The Debug Log - **Time:** 5 minutes at the end of each Hour - **Materials:** a notebook or a single plain file, dated entries - **Safety and privacy:** keep names of friends and family out of it; it may end up in a portfolio - **The fun:** in a month it reads like a detective's casebook - **The skill:** a dated log of symptom, Expected/Actual, hypothesis, test, fix, lesson, and minutes - **The crumb:** a monthly log page **How it goes.** Here is one entry, as an illustration: > **14 Oct.** Symptom: grader crashes on an empty answer sheet. Expected: 0. Actual: `ZeroDivisionError` on line 7. Hypothesis: it divides by the number of answers, which is zero. Test: `assert score_quiz([], KEY) == 0` (fails before the fix). Fix: divide by the number of questions in the key. Lesson: the percent is out of the questions, not out of what the student wrote. 55 minutes. That last line, the lesson, is what makes a log worth keeping. At the end of each month the student reads the month's entries and writes one sentence about the bug they meet most often. Chapter 9 uses those pages as evidence for credit. ### In-home — TEST-03 A Real Test File - **Time:** 30 minutes - **Materials:** the editor, a terminal or the editor's Run button - **Safety and privacy:** none needed - **The fun:** one command, a whole page of promises checked - **The skill:** moving asserts into a test file and running them every change - **The crumb:** a `test_` file and a short run log **How it goes.** The function lives in `grader.py`, with no `print` calls at the bottom. Here's the fixed version: ```python def score_quiz(answers, key): """Return the percent of questions answered correctly.""" right = 0 for given, correct in zip(answers, key): if given == correct: right += 1 return round(100 * right / len(key)) ``` The tests live in `test_grader.py`, in the same folder: ```python from grader import score_quiz KEY = ["b", "c", "d"] assert score_quiz(["b", "c", "d"], KEY) == 100 # all right assert score_quiz(["b", "c", "a"], KEY) == 67 # two of three assert score_quiz(["a", "a", "a"], KEY) == 0 # none right assert score_quiz([], KEY) == 0 # empty sheet assert score_quiz(["b"], KEY) == 33 # stopped early print("All 5 tests passed.") ``` Running `python3 test_grader.py` (or pressing Run with the test file open) prints `All 5 tests passed.` With the first version of the grader, the same file stops on the empty-sheet test with `ZeroDivisionError`. That's the order to teach: write the test that reproduces the bug, watch it fail, fix the code, watch it pass, and keep the test forever so the bug can't sneak back. **17–18:** every project from here on has a test file, and "done" includes "the test file passes." **Ready 16:** a 16-year-old who's comfortable with files from Chapter 2 can start this now. One thing to notice together: what should happen if the *key* is empty? The spec doesn't say. That's the next row. ### In-home — TEST-05 First User, Weekly - **Time:** 15 minutes - **Materials:** the student's program, you, a note card - **Safety and privacy:** use made-up data - **The fun:** you get to be the most confusing user in the world - **The skill:** the parent uses the program like a stranger and reports, without fixing - **The crumb:** a first-user note **How it goes.** You've been first user since **The Computing Hour**. This week, add one rule: everything surprising you find becomes a test row before it becomes a fix. Use it like a stranger: press Enter with nothing typed; type a word where a number belongs; type a huge number. Report what you saw in one plain sentence ("When I left it blank, red text filled the screen"). Don't diagnose. Don't touch the keyboard after your turn. The student writes the test, then the fix. **15–16:** every session. **17–18:** weekly, with the student choosing which feature you test. ### In-home — BUG-04 Bisect the Bug - **Time:** 20 minutes - **Materials:** a program of 40 lines or more with a bug the student can't find, or a week of saved versions - **Safety and privacy:** work on a copy - **The fun:** a bug in a thousand lines found in ten steps - **The skill:** halving the code or the history to find where the bug starts - **The crumb:** bisect notes **How it goes.** The student writes down a test that shows the bug. Then they disable the second half of the program (comment it out, or return early from the function) and run the test. Still broken? The bug is in the first half. Fixed? It's in the second. They write down each step: "Lines 1–40: bug. Lines 1–20: no bug. Lines 21–30: bug…" until one line is left. With saved versions, the same idea works on time: test Monday's version and Friday's, then Wednesday's, and so on. Chapter 6 shows the Git command that automates this. **17–18:** the default method for any bug that survives one Hour. **Ready 16:** a 16-year-old with tidy, numbered saved versions can do the history version now. ### Out-of-home — OUT-01 Algorithms in Public - **Time:** 20 minutes - **Materials:** a pocket notebook - **Safety and privacy:** watch machines, not people; no photos of strangers; first names only if you talk to staff - **The fun:** finding bugs in the real world - **The skill:** writing a spec for a self-checkout, an elevator, or a traffic signal from observation - **The crumb:** a spec page **How it goes.** In Chapter 1 the student watched a public machine and wrote its spec. This week they go back out hunting for a *bug in the world*: a confusing sign, a parking-payment kiosk that rejects a valid card, or a form that asks for a middle name and won't accept "none". They write it as Expected/Actual ("I expected the kiosk to take a card after I chose 'pay.' It asked me to choose 'pay' again"), then a guess about the cause, then a test that would prove the fix. The point is noticing that every confusing thing in public is a failed test someone didn't write. **15–16:** go together and compare notes. **17–18:** the student goes alone and brings back two. ### Talk box (this chapter) **Opening:** "What did you expect, what happened instead — and what test would prove the fix?" **Follow-ups:** 1. **Prediction:** "Before you run it again, which test do you think will fail now?" 2. **Evidence:** "What does the last line of the traceback say, in your own words?" 3. **Location:** "Which line is it pointing at, and what's on the line above?" 4. **Change:** "What's the one change you'll make first? Just one." 5. **Revision:** "Now that it passes, what new test would break it?" **How to wait.** Count to five in your head. When the question is about code on the screen, let them read as long as they need. Look at the code, not at the student. **What a stuck silence usually means.** At this age, often that the student is embarrassed the bug was simple. Sometimes it means they haven't written the Expected/Actual line yet, so there's nothing to compare. Sometimes the screen is louder than the question; lower the lid for a moment and ask again. And sometimes it means they already know the answer and are waiting to see whether you'll fix it for them, because you have before. **Don't say / say instead.** Don't say "Did you even test it?"; say "Which test would have caught this? Let's write it now." ### An incorrect example to diagnose Show the student this test, labeled as a broken test: ```python def double(n): return n + n assert double(3) == double(3) # BROKEN TEST: it can never fail print("Passed.") ``` It prints `Passed.` every time. Ask: "If `double` were completely wrong, say it returned `n * 3`, would this test catch it?" It wouldn't. The test compares the function with itself. A test has to compare against an answer the student worked out independently, on paper, before running: `assert double(3) == 6`. A test that can't fail proves nothing. Spotting it is a real skill. ### Mixed practice Once each card has been done once, mix them. Hand the student a short program with no hint about what's wrong, and let them decide: is this a syntax error, a runtime error, or a logic error? Do I need the traceback card, or a new test, or both? Keep the monthly AS-01 Cold Trace from Chapter 1, and once a week ask for the three kinds of error and the traceback reading order from memory. ## For the student You will spend a lot of your programming life finding mistakes. Everyone does; it's what the job is. The people who get good aren't the ones who make fewer mistakes. They find them faster, because they have a method. The method has two halves. **Tests** are how you know whether there's a problem. **Debugging** is how you find and fix it once you know. **Tests first.** A test is a written promise: "For this input, my program should give this output." You write it before you write the code, while your head is still on what the program *should* do instead of what it *does* do. That order matters. Once you've written the code, your brain starts defending it. Before, you're still honest. A test table looks like this: | Input | Expected | Actual | Pass? | |---|---|---|---| | `["b","c","d"]` | 100 | | | | `["b","c","a"]` | 67 | | | | `[]` (empty sheet) | 0 | | | | `["b"]` (stopped early) | 33 | | | Leave the last two columns blank until you run it. The empty sheet is the edge case, the input at the boundary or the odd one a careless user might type. It's the row that catches the bug, almost every time. **Then asserts.** Each row becomes a line of Python: ```python assert score_quiz([], KEY) == 0 # empty sheet ``` If it's true, nothing happens. If it's false, the program stops and tells you which promise you broke. Write all your asserts, predict which will fail, then run them. **Try this today.** Pick a function you wrote in Chapter 2. Write four test rows for it: two normal, one boundary, one bad input. Turn them into asserts. Then break the function on purpose (change one symbol) and check that at least one test catches it. If none do, your tests aren't testing anything yet. Fix the tests, not the function. **When it breaks.** You'll see red text. Here's the order: 1. Write the Expected/Actual line before you touch anything. "I expected 0. It crashed." 2. Read the **last line** of the traceback. That's what happened. 3. Read the line just above it. That's where. 4. Make one guess about why. 5. Change **one thing**. Run *all* the tests. 6. Write a Debug Log entry: symptom, Expected/Actual, hypothesis, test, fix, lesson, minutes. Step 5 is the one people skip. Change three things at once and, even if it works, you won't know which change fixed it, and one of the others may have quietly broken something. One change, one run. It feels slower. It's much faster. **Before you rewrite.** At some point you'll want to delete the file and start over. Sometimes that really is the right call. But make it a decision, not a reaction. Read your Debug Log first. If you have a hypothesis you haven't tested, test it. If you've tested three and they all failed, then maybe a rewrite makes sense, and now you know three things the new version has to get right. **Explain it back.** Pick one bug you fixed this week. Explain to someone (a parent, a sibling, or a rubber duck on your desk) what the bug was, how you found it, and why your fix works. If you can't say why the fix works, you got lucky, and luck doesn't repeat. **This part is hard for everyone.** Thinking of edge cases is hard. Your brain wants to test the inputs you were already imagining when you wrote the code, which are exactly the inputs that work. Use your first user. When a parent types nothing and presses Enter, they're doing you a favor. **About pride.** It feels great when all the tests pass. Enjoy it. That feeling is earned. But notice the order: proof, then pride. If a test fails and it stings, remember that the test just saved you from a stranger finding it. A failing test is the bug's address. **If you're 17 or older:** keep your tests in their own file, `test_` plus the name of the file it tests, and run it after every change. When you fix a bug, write the test that reproduces it *first*, watch it fail, then fix the code and watch it pass. Commit the test and the fix together. If you ever use an AI coding assistant on your one named project (see the AI box in **The Computing Hour**), every line it suggests gets the same treatment as your own code, and more: you explain each line before you keep it, and your tests decide whether it works, not the tool's confidence. **Challenge.** Take the best function you've written so far. Write three new tests designed to break it. If you can't break it, ask your first user to try. If they break it, write the test, fix the function, and log it. That's a good week. **What to save:** your test table (dated), your test file or asserts, and this week's Debug Log pages. Save them in two places. ## If it isn't clicking **The student deletes failing tests.** Usually tests feel like grades, and a failing one feels like a bad mark. Reframe it out loud: "A failing test isn't a grade. It's the bug's address." Make a family rule that no test gets deleted without a one-line note in the Debug Log saying why, and a matching change to the spec if the expected answer changed. **The student changes several lines at once.** That's usually panic, impatience, or both. Slow the loop down by saying it out loud together for a week: "One change. Run. What happened? Log it." If they really want to try several ideas, they can list them first in the log, then try them one at a time. **The same bug keeps coming back.** There's no regression test, a test that stays in the file after a fix so the bug can't quietly return. Next time it appears, the first move is to write the test that would have caught it, watch it fail, and keep it forever. **Red text causes a shutdown.** The student freezes, or walks away, or says "It's broken." Go back to BUG-02 with a printed traceback and the colored pencils. Read only the last line together. Say, in your calmest voice, "That's a clue, not a verdict." Then follow the rescue order: ask → wait → hint → short demo on your own copy → hand it back. If you demo, demo on your own copy of the file, and hand back the student's copy untouched. **When to get outside help.** Three Hours stuck on one bug, with honest log entries, is a good moment for a second pair of eyes: a co-op class, a tutor, or an adult who codes at work (OUT-03 in Chapter 6). Bring the Debug Log. ## Tools, including AI Your student's editor is enough: Thonny for 15–16 if it's still new, or any free code editor with a terminal at 17–18. Thonny's step-through mode, which runs a program one step at a time so you can watch the variables change, is a fine debugging tool at any age.^[13](#note-13)^ Adding temporary `print()` lines to show what a variable holds is also real debugging, as long as the student removes them afterward. For AI, the rules are the ones in the AI box in **The Computing Hour**, and they matter especially here. Chat-style help may explain an error message only after the student has written their own Expected/Actual line and guess. At 17, on the one named project, a suggested fix stays only after the student explains every line of it (AI-05 Explain Every Line, Chapter 8) and the full test file passes. AI is off for every check, including AS-02 and AS-06 below. The tests, not the tool, decide whether code works. Check the current terms. ## What "done enough" looks like Move on when most of these are "seen," a few are "growing," and none of the core four (the first four) is "not yet": - [ ] Writes a test table, including a boundary and a bad input, before writing code (TEST-01, TEST-04) - [ ] Turns test rows into asserts and has seen a test fail on purpose (TEST-02) - [ ] Reads a traceback bottom-up and names the error type, message, and line (BUG-02) - [ ] Writes Expected/Actual before touching code, and keeps a Debug Log with lessons (BUG-01, BUG-05) - [ ] Has found three planted bugs, one of each kind (BUG-03) - [ ] Turns first-user surprises into tests before fixes (TEST-05) - [ ] **AS-02 Debug on the Spot:** fixes a bug you planted while explaining aloud, with no AI and no help. You write one line about how it went. - [ ] **AS-06 Spec-to-Test Check:** given a short spec written by someone else, writes a test table for it, unaided, in 15 minutes. Date it and keep it for Chapter 9. - [ ] **17–18:** keeps a test file for every project and runs it after every change (TEST-03); has bisected at least one bug by halves (BUG-04, below). **Placement.** Place by skill, not birthday. A 15-year-old who writes tests first and logs calmly is ready for Chapter 4. A 17-year-old who still deletes failing tests needs another week here, and that's not a failure. \newpage # Chapter 4 ## Objects and Classes: The Bridge to Java ![Index cards laid out as a class diagram, boxes joined by pencil lines, beside a closed notebook and a coffee cup — still life, no people, no logos, no readable text.](art/ch04-opener.jpg){width=100%} ## Why this matters Here is an illustration, not a real family. Picture a sixteen-year-old who has spent three weeks on a program that tracks the family's library books. It works. It also has six separate lists (titles, authors, pages, due dates, who borrowed it, whether it's back), and every function takes all six as arguments. When he adds a seventh list for "rating," he has to change eleven lines in nine places, and he misses one. The program doesn't crash. It just quietly starts pairing the wrong rating with the wrong book. He doesn't need to work harder. He needs a better shape. What he's missing is the idea that a book is one *thing*, with its own facts and its own actions, and that the program should be built out of things like that. That idea is called an **object**, and the blueprint for making objects of one kind is called a **class**. A class is a blueprint; an object is one thing built from it. The `Book` class says every book has a title and a page count and can describe itself. Each actual book on the shelf is an object. Classes are the biggest new idea of high-school programming. They change how a student thinks about a program: not a long list of steps, but a small cast of characters, each responsible for what it knows. They make big programs readable, and they make changes safer, because the code that knows about pages lives in one place. Classes are also the bridge to a second language. This chapter builds the same small program in Python, then in **Java**. Java is a real strand of this book, not a sidebar. It's widely used in industry and in college courses, and it makes visible things that Python keeps quiet: what **type** each value is (a whole number, text, a true-or-false), where each block of code starts and stops, and the moment when the whole program is checked before it runs. Java **compiles**: it translates the whole program first, and refuses to run if something doesn't fit. Python doesn't; it finds problems as it reaches them. Learning both teaches a student what a programming language *is*, which is something no single language can teach. There's an honest limit to say once. Object-oriented programming isn't "the right way" to program. It's one way, common in industry and central to the AP Computer Science A course, which is taught in Java. Other styles exist and are good. A student who understands objects well can learn those too. And AP CSA? It's an option, not the point of this chapter. Some families will want it; many won't. This chapter teaches Java because Java is worth learning. If your student later decides to sit the AP exam, the "Tools" section and Chapter 9 explain how that works for homeschoolers. ## For the parent: understand it yourself You don't need to write Java to teach this chapter. You need to tell a class from an object, recognize the three or four parts of a class, and know what a compiler error looks like so you can say "Read me the first one" instead of "Oh no." **The everyday picture.** A recipe card for muffins is a class. It says what every batch has (flour, sugar, a number of muffins) and what you can do with it (bake, count, describe). The actual tray of muffins on your counter is an object. You can make three trays from one card, and each tray has its own count: one has twelve, one has eleven because somebody tested one. Changing the count on one tray doesn't change the card or the other trays. **The precise picture.** The national high-school standards from the Computer Science Teachers Association put it this way: "Create a modular program that uses procedures, external libraries, or objects to improve reusability and readability."^[21](#note-21)^ Notice the purpose: reusability and readability. Objects are a way to write code other people (including your student, next month) can read and reuse. ### A class in Python Here is a small `Book` class: ```python class Book: def __init__(self, title, pages): self.title = title self.pages = pages def is_long(self): return self.pages > 400 def describe(self): return f"{self.title}, {self.pages} pages" b = Book("The River Map", 312) print(b.describe()) print(b.is_long()) ``` It prints `The River Map, 312 pages`, then `False`. Read it in parts: - **`class Book:`** starts the blueprint. - **`__init__`** (said "init," with two underscores on each side) is the setup step. It runs once, when a new book is made, and stores the title and page count. These stored facts are called **attributes**. - **`self`** means "this particular book." When the code says `self.pages`, it means *this* book's pages, not some other book's. - **`is_long` and `describe`** are **methods**: things a book can do. A method is a function that belongs to a class. - **`b = Book("The River Map", 312)`** makes one object from the blueprint. You can make as many as you like. ### The same class in Java Now the same idea in Java. Java likes each class in its own file, so `Book` goes in `Book.java`: ```java public class Book { private String title; private int pages; public Book(String title, int pages) { this.title = title; this.pages = pages; } public boolean isLong() { return pages > 400; } public String describe() { return title + ", " + pages + " pages"; } } ``` And a second file, `Main.java`, holds the starting point: ```java public class Main { public static void main(String[] args) { Book b = new Book("The River Map", 312); System.out.println(b.describe()); System.out.println(b.isLong()); } } ``` In a terminal, `javac Book.java Main.java` compiles both files, and `java Main` runs the program. It prints `The River Map, 312 pages`, then `false` (Java writes true and false in lowercase). Same program. Here's what Java makes you say out loud that Python didn't: - **Types.** `String title` and `int pages` say exactly what kind of value each attribute holds. `boolean isLong()` says the method hands back a true-or-false. - **`private`** means only the `Book` class itself can change the title and pages. Other code has to ask a method. This is the "who gets to change it?" in the talk box. - **The constructor**, `public Book(...)`, plays the part of Python's `__init__`. It has the same name as the class. - **`new`** is required to make an object: `new Book(...)`. - **Braces and semicolons.** `{` and `}` mark where each block starts and stops; Python uses indentation instead. Every statement ends with `;`. - **`main`.** A Java program starts at a method called `main`. Its first line looks like a spell (`public static void main(String[] args)`); for now, it's just "the door the program comes in by." ### Compile, then run The biggest difference isn't the punctuation. It's *when* mistakes show up. Here's a short Java program with two deliberate bugs, labeled: ```java public class Main { public static void main(String[] args) { int pages = "300"; // DELIBERATE BUG 1: text, not a number System.out.println(pages) // DELIBERATE BUG 2: missing semicolon } } ``` When we compiled it, Java reported only one error, the missing semicolon: `Main.java:4: error: ';' expected`. Nothing ran. After the semicolon was added and the file compiled again, Java reported the next one: `Main.java:3: error: incompatible types: String cannot be converted to int`. Fix that (`int pages = 300;`) and it compiles and runs. That's a lesson worth a whole Hour. Java checks before it runs, and it often reports problems one layer at a time: fix the first error, compile again, read the next. A wall of red after compiling isn't a hundred problems. Usually it's one, plus its echoes. The habit is: **first error first**, then compile again. Python, by contrast, would have run happily until it reached the bad line. ### Wrong answers you should be able to hear - **"A class and an object are the same thing."** One example has blurred them. Ask: "If `Book` is the card, how many books can you make from it? Make me three." - **"It says `takes 0 positional arguments but 1 was given`."** In Python, the method forgot `self` as its first parameter. When we ran a version of `is_long` written as `def is_long():`, Python said exactly that: `TypeError: Book.is_long() takes 0 positional arguments but 1 was given`. Python hands every method the object itself, and the method has to have a place to put it. - **"Java says `cannot find symbol`."** Often `new` is missing. `Book b = Book("The River Map", 312);` gives `error: cannot find symbol`, because without `new`, Java goes looking for a method named `Book` and doesn't find one. (The same error also appears for typos in names, so read the line it points at.) - **"Java is just harder Python."** Types and structure feel like noise. Ask: "What does the type tell you that Python didn't?" - **"Seven divided by two is three?"** In Java, dividing two whole numbers gives a whole number. `7 / 2` prints `3`; `7 / 2.0` prints `3.5`. Python's `7 / 2` gives `3.5`, and Python has a separate `//` for whole-number division (`7 // 2` gives `3`). Neither is wrong. They're different promises. - **"The two strings are equal but Java says false."** In Java, `==` on text checks whether two variables point at the very same object, not whether the letters match. Use `.equals`. When we ran it, comparing `"yes"` with `new String("yes")` gave `false` with `==` and `true` with `.equals`. In Python, `==` compares the letters. So there are three ideas to keep apart: `=` stores a value, `==` compares, and in Java, `.equals` compares text. ### Your five-minute warm-up Take three index cards. Write "Book" on the first and list two attributes (title, pages) and two methods (is long?, describe). That's the class. On the other two cards, write two actual books from your shelf, with their own titles and page counts. Those are objects. Put the class card above the two object cards. Then say this chapter's opening question once, out loud: "What does this object know, what can it do — and who gets to change it?" That's the whole preparation. ## How to teach it this week Run the week inside the six steps of **The Computing Hour**, and expect it to take two weeks rather than one. Classes are new, and Java is a second language. Both deserve time. - **Specify.** The spec now names the *things* in the program before it names the steps: "A `Book` knows its title and pages and can say whether it's long." Each class gets one line of responsibility. - **Predict.** "What will `describe()` print for this book?" At 17–18 in Java: "Will this compile? If not, which line will Java complain about first?" - **Build and Test.** One class at a time. Make one object, call one method, check the result. Tests from Chapter 3 continue: an `assert` on `describe()` in Python, a printed check in Java. - **Debug and Log.** Java compile errors go in the Debug Log like any other: Expected/Actual, the first error's line and message, one change, compile again. - **Review.** Look at the class with fresh eyes: is anything in it that doesn't belong to a book? Is anything outside it that does? - **Ship and Explain.** "I specified… I predicted… It did… Next I'd change…" and "Help I used: …" **Day 1: cards before code.** The whole first Hour can be unplugged. ### In-home — OOP-01 Index-Card Objects - **Time:** 15 minutes - **Materials:** index cards, two colors of pen - **Safety and privacy:** use made-up names or objects from around the house - **The fun:** you become a method - **The skill:** cards as objects, with attributes on the front and methods on the back - **The crumb:** a card set **How it goes.** The student picks something the family owns many of: books, plants, bikes, board games. On one card they write the class: its name, the attributes every one of them has, and two or three things it can do. Then they make three object cards from it, each with its own values on the front and the same methods on the back. To "call a method," the student hands you an object card and says "describe." You do exactly what the back of the card says, using only the facts on the front. If the back says "say the title and pages," you say exactly that, nothing more. Every time you have to guess, there's a gap in the class. **15–16:** you play the method; the student designs the cards. **17–18:** add a second class that uses the first (a `Shelf` that holds several `Book` cards and can count their pages) and play it out with real cards on the table. **Day 2: the first class in Python.** ### In-home — OOP-02 Your First Class - **Time:** 30 minutes - **Materials:** the editor, yesterday's cards - **Safety and privacy:** no real people's names in the data - **The fun:** the card set comes to life - **The skill:** a Python class with `__init__`, attributes, and two methods - **The crumb:** the program file **How it goes.** The student types the class from their card set, not from the book. Start with `__init__` and one method. Make one object. Print one thing. Then add the second method and a second object. Each run is preceded by a written prediction. Add two `assert` lines from Chapter 3 at the bottom, one for each method. If they're using the `Book` example, a good test is `assert b.describe() == "The River Map, 312 pages"`. **15–16:** sit nearby and be first user: make an object with a page count of 0, or of 401, and report what you saw. **17–18:** the student adds a method that changes an attribute (a `mark_returned()` that sets `self.returned = True`) and writes a test that proves it changed only that one object. **Days 3–4: the same program in Java.** This is the bridge. ### In-home — OOP-03 Same Program, in Java - **Time:** 40 minutes (often split over two Hours) - **Materials:** a free Java Development Kit (JDK) and a plain editor, or a browser-based Java editor if the family's rules allow it; Tuesday's Python file - **Safety and privacy:** install only from the official source for the JDK; a parent decides on any browser tool and its account - **The fun:** watching the same idea wear different clothes - **The skill:** rewriting a small Python class in Java: types, braces, `main`, compile then run - **The crumb:** two files side by side **How it goes.** The Python file stays open on one side. The student writes the Java version beside it, line by matching line, saying the translation out loud: "`__init__` becomes the constructor. `self.pages` becomes `this.pages`. And I have to say `pages` is an `int`." Then compile. Expect errors, and plan for them. The first compile almost always fails, and that's the lesson. Read the first error only. Fix it. Compile again. Log each one. Picture a fifteen-year-old whose log entry after the first Java Hour reads: "Java tells me before it runs. Python told me when it ran." That sentence is most of this chapter. **15–16:** the student copies the shape of `Book.java` and `Main.java` from this chapter, then changes them to match their own card set. **17–18:** the student writes the Java version without looking at the book's, using the Python file and Java's own error messages as the only guides. **Day 5: the diagram.** ### In-home — OOP-04 Class Diagram on Paper - **Time:** 15 minutes - **Materials:** paper, pencil, a ruler if you like straight lines - **Safety and privacy:** none needed - **The fun:** seeing the whole program on one page - **The skill:** boxes and arrows for two classes that work together - **The crumb:** the diagram **How it goes.** Each class is a box with three parts: its name at the top, its attributes in the middle (with types, at 17–18), its methods at the bottom. An arrow from `Shelf` to `Book` says "a shelf holds books." The student draws the diagram for the program they're building, then answers out loud: "Who knows the page count? Who knows the total? If the total is wrong, which box do I open first?" **15–16:** two classes. **17–18:** three classes, and a sentence under each box saying what it's responsible for, and what it's *not*. **Fading help.** Week one, you may need to say "first error first" every time Java complains. Week two, point at the first line of the error. By week three, the student reads it to you. When they ask for rescue, use the rescue order from **The Computing Hour**: ask → wait → hint → short demo on your own copy → hand it back. Good hints in this chapter: "Which card would know that?" and "What type is it?" ## Practice that actually builds learning Practice starts blocked (one class, several objects; then the same class in both languages) and becomes mixed (deciding *which* class a new piece of information belongs to). ### In-home — PY-06 Paper Parsons, Python Edition - **Time:** 10 minutes - **Materials:** a working Java method cut into strips, plus one distractor strip - **Safety and privacy:** none needed - **The fun:** a puzzle with a trap in it - **The skill:** reordering cut-up lines into a working function - **The crumb:** the taped strip **How it goes.** You met Parsons puzzles with Python in Chapter 2. This week, print the `Book` constructor and its `describe` method in Java, cut it into one line per strip, shuffle, and add one distractor (a Python line like `self.pages = pages`, or a Java line with a missing semicolon). The student orders the strips, tapes them down, and says why the distractor doesn't belong. Matching braces is half the puzzle, which is the point. ### In-home — OOP-05 Arrays and ArrayLists - **Time:** 30 minutes - **Materials:** the editor and JDK - **Safety and privacy:** none needed - **The fun:** a game board in nine lines - **The skill:** Java arrays and ArrayLists, loops over them, a 2D grid - **The crumb:** a Java file plus a trace on paper **How it goes.** A Java **array** holds a fixed number of values of one type. Its size is set when it's made. An **ArrayList** is a list that can grow, like a Python list. Start with the array: ```java public class Arr { public static void main(String[] args) { int[] scores = {88, 92, 75}; System.out.println(scores.length); System.out.println(scores[3]); // DELIBERATE BUG: there is no index 3 } } ``` It prints `3`, then crashes with `ArrayIndexOutOfBoundsException: Index 3 out of bounds for length 3`. Three items are numbered 0, 1, and 2, just as in Python. (This is a runtime error: Java compiled it happily, because the compiler checks types, not which numbers you'll ask for.) Then an ArrayList that grows: ```java import java.util.ArrayList; public class Shelf { public static void main(String[] args) { ArrayList pages = new ArrayList<>(); pages.add(312); pages.add(95); pages.add(540); int total = 0; for (int p : pages) { total += p; } System.out.println(pages.size() + " books, " + total + " pages"); } } ``` It prints `3 books, 947 pages`. Notice `Integer`, not `int`, inside the angle brackets; ArrayLists hold objects, and `Integer` is the object version of a whole number. That's a fact to know, not to understand fully this week. Finally, a **2D array**, a grid of rows and columns, which is how many board games are stored: ```java public class Grid { public static void main(String[] args) { char[][] board = new char[3][3]; for (int r = 0; r < 3; r++) { for (int c = 0; c < 3; c++) { board[r][c] = '.'; } } board[1][2] = 'X'; for (char[] row : board) { System.out.println(new String(row)); } } } ``` It prints three rows: `...`, then `..X`, then `...`. Before running it, the student traces it on paper (a 3-by-3 grid of boxes) and predicts where the X lands. Row 1, column 2 is the middle row, right-hand column, because both count from zero. **17–18:** all three. **Ready 16:** a 16-year-old who's comfortable with Python lists and nested loops from Chapter 2 can take this on now. ### Out-of-home — OUT-03 Ask a Working Programmer - **Time:** 30 minutes - **Materials:** five questions written in advance; a notebook - **Safety and privacy:** an adult the family knows (a relative, a co-op parent, a neighbor); meet in a public place or by video with a parent present; first names only in notes - **The fun:** finding out what the job is actually like - **The skill:** a short interview with an adult who writes code at work - **The crumb:** interview notes (first name only) **How it goes.** The full version of this try-it lives in Chapter 6, and many families will do it there. If your student is curious now, do a short version this week with one question about objects: "How does your team decide what goes in a class?" or "What's a class in your code that got too big, and what did you do?" Most working programmers have a story. Write down the answer in the student's words, and add one follow-up question they'd ask next time. ### Talk box (this chapter) **Opening:** "What does this object know, what can it do — and who gets to change it?" **Follow-ups:** 1. **Prediction:** "If I make a second book and change its pages, what happens to the first one?" 2. **Evidence:** "Which line in the class makes that true?" 3. **Location:** "Where does the page count live? Point to it." 4. **Change:** "If we added a due date, which class would get it, and what would change in the Java version?" 5. **Revision:** "Is there anything in this class that doesn't belong to a book?" **How to wait.** Count to five in your head. When the question is about code on the screen, let them read as long as they need. Look at the code, not at the student. **What a stuck silence usually means.** Often that the student is translating between languages in their head and lost track of which one you asked about. Point at the file. Sometimes it means the class and object are still blurred; go back to the cards on the table. And sometimes the student knows the answer and is checking whether you'll accept a Python answer to a Java question. Ask for both. **Don't say / say instead.** Don't say "Java is just picky"; say "Java is telling you before it runs. What's it telling you?" ### An incorrect example to diagnose Show the student this Python class, labeled as a poor design: ```python class Library: def __init__(self): self.titles = [] self.pages = [] self.due_dates = [] self.borrowers = [] ``` It runs. Nothing is wrong, exactly. Ask: "If someone adds a book's title but forgets its page count, what happens to every book after it?" The lists drift out of line, which is the bug from this chapter's opening. Then ask: "What would a `Book` class fix?" Each book keeps its own facts together, so they can't drift. Finding the *shape* problem, not just the line problem, is what this chapter is for. ### Mixed practice Once the cards and the first classes are done, mix it up. Hand the student a list of facts and actions ("a due date," "renew," "count all overdue books," "the borrower's first name") and have them decide which class each belongs to, on paper, before any code. Mix in Java and Python: one Hour in each, same project. Keep the monthly AS-01 Cold Trace, using a short class this time: "What will this print?" ## For the student So far your programs have been lists of steps with some data floating around them. This chapter changes the shape. From now on, you'll build programs out of **objects**: things that hold their own facts and know how to do their own jobs. **The idea.** A class is a blueprint. An object is one thing built from it. `Book` is the class: every book has a title and a page count and can describe itself. "The River Map, 312 pages" is one object. Make a hundred objects from one class, and each keeps its own facts. Here's the Python version: ```python class Book: def __init__(self, title, pages): self.title = title self.pages = pages def is_long(self): return self.pages > 400 ``` `__init__` runs when a new book is made. `self` means *this* book. `is_long` is a method, a function that belongs to the class. `Book("The River Map", 312).is_long()` gives `False`. **Now Java.** Java says the same thing with more words, and every extra word means something: ```java public class Book { private String title; private int pages; public Book(String title, int pages) { this.title = title; this.pages = pages; } public boolean isLong() { return pages > 400; } } ``` `String` and `int` are types. `private` means only `Book` can change these. The constructor has the class's name. Braces show where blocks start and stop. Semicolons end statements. To make a book, you write `new Book("The River Map", 312)`. **Compile, then run.** Java checks the whole program before it runs a single line. That's annoying for about a week, and then it's useful: Java catches a whole family of mistakes that Python only finds when it reaches them. When Java reports errors, read the **first** one, fix it, and compile again. The others are often echoes, and sometimes the next error is hiding behind the first. **Try this today.** Pick something you own several of (books, games, plants, tools). On an index card, write its class: two attributes and two methods. Write it in Python with two objects and a test for each method. Then write it in Java. Keep both files open side by side. Your first Java compile will probably fail. Good. Log every error: line, message, fix. **Explain it back.** Point at your Java file and explain, to a parent or a sibling, what each of these does: `private`, the constructor, `new`, and the type in front of each method. Then explain what Python did instead for each one. If you can do that, you understand both languages better than if you'd only learned one. **This part is hard for everyone.** Types and semicolons. You'll forget a semicolon. You'll put text where a number belongs. You'll write `==` when you meant `.equals` on two strings and get `false` for two words that look identical. Everyone who learns Java does all of these, usually in the first week. The fix is the same as in Chapter 3: read the message, change one thing, log it. One more trap: in Java, `7 / 2` is `3`, because two whole numbers make a whole number. Use `7 / 2.0` when you want `3.5`. **Who gets to change it?** This is the question that makes classes worth it. When `pages` is `private`, the only code that can change it is inside `Book`. If the page count ever goes wrong, you know exactly where to look. That's a big deal in a program with a thousand lines, and it's how professional teams keep big programs from turning into tangles. **If you're 17 or older:** learn arrays, ArrayLists, and 2D arrays this month (OOP-05). Then build a small grid game: a 3-by-3 or 5-by-5 board, a class for the board, a method to place a piece, and a method that checks whether a move is allowed. Write tests for the edges: what happens at row 0? At the last column? Outside the board? If you're thinking about the AP Computer Science A exam, know that it's in Java and that its written section asks you to write methods, design a class, work with an ArrayList, and work with a 2D array. Your grid game touches all four. AP is a choice, not a requirement; talk with your parent about whether it fits your plans. **A worked translation.** Here's how one line moves between the languages, said the way you'd say it to a teammate. Python: `self.pages = pages`. Java: `this.pages = pages;`. Same idea: store the value you were handed in this object's own attribute. Python: `def is_long(self):`. Java: `public boolean isLong() {`. Java adds who may call it (`public`), what it hands back (`boolean`), and braces where Python used a colon and indentation. Python names use underscores (`is_long`); Java's custom is capitals in the middle (`isLong`). Neither is right; each language has its habits, and following them is part of writing code other people can read. **Reading a Java error.** Java's messages have a shape: the file, a colon, the line number, the word `error`, and a short description, then the line itself with a caret under the spot. `Main.java:4: error: ';' expected` means "file Main.java, line 4, I expected a semicolon." Copy that first line into your Debug Log before you change anything. After a week you'll recognize the five or six messages you see most, and they'll stop feeling like insults. **Challenge.** Build a 2D grid game board as a class, in Java, with a `place(row, col)` method that refuses moves outside the board instead of crashing. Write three tests, one of them for a move that should be refused. Then write the same class in Python and compare. Which language caught more of your mistakes before you ran it? **What to save:** your index cards (a photo is fine), both program files, your class diagram, and the Debug Log pages with every compile error you met. Save them in two places. ## If it isn't clicking **Class and object are still confused.** One example blurred them. Go back to the cards: one class card, three object cards, each with different values. Ask: "If I change this one's pages, what happens to the others?" Then make three objects in code and print each. **Java errors feel hostile.** The compiler's messages aren't being read; they're being looked at. Read them top-down, first error first, out loud. Copy the first error's line number and message into the Debug Log before touching anything. Within a week, most students find Java's messages more helpful than Python's, because they arrive before anything runs. **Everything ends up in one giant class.** There's no sense yet of who's responsible for what. Back to OOP-04: draw the boxes and ask, for each fact, "Who would know this?" A `Shelf` knows how many books it holds. A `Book` knows its own pages. Nobody else should. **Java itself is the obstacle.** Some students hit a wall with the second language. That's fine. Slow down, stay in Python for classes for another two weeks, and come back to Java with one tiny class. If Java still doesn't stick, a co-op class, a tutor who knows Java, or a dual-enrollment course (Chapter 9) can carry the strand. When you ask for rescue, the order is the same as ever: ask → wait → hint → short demo on your own copy → hand it back. ## Tools, including AI For Java, a free Java Development Kit (the JDK) plus a plain editor is enough: `javac` compiles, `java` runs. Install the JDK only from its official source. A browser-based Java editor is an option if the family's rules allow it; a parent decides on the account and checks the current terms. Any free code editor that handles Python will handle Java too. No brand matters here.^[22](#note-22)^ The AI rules are the ones in the AI box in **The Computing Hour**. At 15–16, chat-style help may explain a Java error message after the student has written their own Expected/Actual line and guess. The editor coding assistant stays off through 16, and for every check. Translating Python into Java is exactly the kind of work an assistant does instantly and a student learns from by doing slowly, so keep this chapter's translation work the student's own. At 17, on one named project after AS-04 Build From a Blank, every suggested line still gets explained before it's kept. **AP Computer Science A, if your family is considering it.** The course and exam are built around Java. The current framework took effect in fall 2025. The exam has a multiple-choice section and four free-response questions: one on methods and control structures, one on class design, one on data analysis with an ArrayList, and one on a 2D array.^[23](#note-23)^ Homeschooled students take AP exams at an authorized school, arranged through that school's AP coordinator. Ask a coordinator by early fall; the final ordering deadline falls in mid-November, and exams are given in the first two weeks of May.^[24](#note-24)^ Putting "AP" in a course title on your transcript is a separate step, the AP Course Audit (Chapter 9). This chapter covers the Java a student needs for much of the course, but it isn't an AP prep book, and the exam is optional. ## What "done enough" looks like Move on when most of these are "seen," a few are "growing," and none of the first three is "not yet": - [ ] Explains the difference between a class and an object, using a real example (OOP-01) - [ ] Writes a Python class with `__init__`, two attributes, and two methods, with tests (OOP-02) - [ ] Writes the same class in Java, compiles it, and reads compiler errors first-error-first (OOP-03) - [ ] Draws a class diagram for two classes that work together, saying what each is responsible for (OOP-04) - [ ] Explains `=` versus `==` versus `.equals`, and why `7 / 2` is `3` in Java - [ ] **AS-03 Explain Your Code:** teaches back their own Java class, line by line, to you. You write one line about how it went. - [ ] **AS-01 Cold Trace:** traces a short class and its method calls on paper and predicts the output, unaided. - [ ] **AS-02 Debug on the Spot:** fixes a Java compile error you planted (a missing semicolon or a wrong type) while explaining aloud. - [ ] **17–18 (ready 16):** uses an array, an ArrayList, and a 2D array in Java, and traces the 2D grid on paper (OOP-05). **Placement.** Place by skill, not birthday. A 15-year-old who writes classes in both languages and can explain `private` is ready for Chapter 5. A 17-year-old who still mixes up class and object needs another week with the cards, and that's normal. Java is a second language; give it a second month if it needs one. \newpage # Chapter 5 ## Data: Questions, Tables, and Databases ![Two printed tables joined by a drawn line between key columns, a bar-chart card and a ruler — still life, no people, no logos, no readable text.](art/ch05-opener.jpg){width=100%} ## Why this matters Here is an illustration, not a real family. Picture a seventeen-year-old who wants to know which month the family uses the most water. She could open a spreadsheet, paste in the meter readings, click the chart button, and get a colorful picture in thirty seconds. It would look convincing. It would also be wrong, because one month's reading is missing, another was typed with a space in it, and the chart's axis starts at 400, which makes a small difference look enormous. She does it differently. She writes the question on a card first. She writes down what each column means and what values are allowed before she looks at a single number. She cleans the file in code and keeps a log of everything she changed. She makes one chart, with an honest axis, and writes a caption that says what the data *can't* show. It takes an afternoon instead of thirty seconds. And when her parent asks "Are you sure?", she can show exactly why. That's what this chapter teaches. Data work starts with a question, not a spreadsheet. The student writes the question, describes the data before collecting it, cleans it in code, answers with one honest chart, and learns why serious data lives in a **database**: organized tables, linked by **keys**, the columns that connect one table to another. A **query** is a question asked of those tables, in a language called SQL (often said "sequel"). Databases are behind nearly every app your student uses, from the library catalog to a shopping cart, and SQL has been the common way to ask them questions for decades. It also matters beyond computing. Teens meet charts constantly: in news stories, in ads, in posts that want them angry or afraid. A student who has made an honest chart, and cut an axis once on purpose to see what it does, reads every other chart differently. That's a real gain. It's a habit of reading, though, not a promise about anything else. One caveat, said once and plainly: two things rising together doesn't mean one causes the other. Ice-cream sales and sunburns rise together, and ice cream doesn't cause sunburn; summer causes both. The chapter comes back to this habit in the talk box. After that, it just asks the question: "What else could explain it?" ## For the parent: understand it yourself You don't need statistics to run this chapter. You need to know what a clean table looks like, why one big table is a trap, and how to ask "Could this data actually answer that?" You can learn all three this week. **The everyday picture.** A recipe box with one card per recipe is a table. Each card has the same fields in the same places: name, servings, time, ingredients. If one card says "serves 4" and another says "four people" and a third leaves it blank, you can't sort the box by servings. Cleaning data is making every card say it the same way. A database is several boxes that refer to each other: a recipe card says "see pantry card 12" instead of copying the pantry details onto every recipe. **The precise picture.** The national high-school standards from the Computer Science Teachers Association describe two of this chapter's skills exactly. One asks students to "Create a data dictionary that describes the name, type, and allowable values for each attribute and the logical relationships between variables in a dataset."^[25](#note-25)^ Another asks them to "Create a data visualization of a multivariate dataset to answer a question or make a classification or prediction."^[26](#note-26)^ Notice that both standards put the description and the question first. The data dictionary comes before the data. The question comes before the chart. ### Four ideas in plain words - **A row** is one thing (one reading, one book, one loan). **A column** is one fact about every row (the date, the title). Every row has the same columns. - **A data dictionary** is a short table about the table: for each column, its name, its **type** (date, whole number, text), and the values allowed. "Reading: whole number, never smaller than last month's." - **Cleaning** is fixing the rows that break the dictionary: stray spaces, "n/a," a number typed into the wrong column. Good cleaning is logged, so anyone can see what changed. - **A key** is the column that links tables. In a library database, every person has a `person_id`, every book a `book_id`, and each loan row just says which person and which book. Nobody's name is typed twice. ### Cleaning in code Here's a small, made-up meter file, with three problems planted on purpose: a reading with spaces around it, a reading of "n/a," and a blank line. ```text date,reading 2026-05-01,10230 2026-06-01,10810 2026-07-01, 11690 2026-08-01,n/a 2026-09-01,12460 2026-10-01,12950 ``` And here's a short Python program that cleans it and keeps a log: ```python import csv clean, log = [], [] with open("readings.csv") as f: for row in csv.DictReader(f): date = (row["date"] or "").strip() text = (row["reading"] or "").strip() if not text.isdigit(): log.append(f"dropped {date}: reading was {text!r}") continue clean.append((date, int(text))) print(len(clean), "good rows") for line in log: print(line) ``` When we ran it, it printed `5 good rows` and `dropped 2026-08-01: reading was 'n/a'`. Three things happened, and one is a surprise worth teaching: 1. `.strip()` removed the spaces around `11690`, so July was kept. 2. The "n/a" row failed the check and was logged, not silently thrown away. 3. The blank line never reached the loop at all. Python's built-in `csv` reader skips completely empty lines on its own, so it doesn't appear in the log. That third one is the lesson: know what your tools do quietly. It's fine for a blank line to vanish. It wouldn't be fine for a real reading to vanish without a trace, which is why the log exists. ### The missing month Now the question. Usage is the change between readings: May to June used 580 units, June to July 880. But August is missing, so the next change, July to September, is 770 units for *two* months. A careless chart would show "Jul–Sep: 770" next to "Jun: 880" as if they were the same kind of bar, or worse, would fill the missing August with zero and show a one-month drop. A missing row is not a zero. The honest chart labels that bar as two months, and the caption says so. ### Why two tables beat one Picture a library-loans spreadsheet with one row per loan: borrower's name, book title, pages, date. Every time Ana borrows a book, her name is typed again. Every time *The River Map* goes out, its title and page count are typed again. If someone misspells "Ana" once, she becomes two people. If the page count is corrected on one row and not the others, the data disagrees with itself. The fix is three tables: **people** (an id and a first name), **books** (an id, a title, pages), and **loans** (an id, which person, which book, and the date). Each fact is written once. The loans table holds only keys and a date. SQL's `JOIN` puts them back together when you ask a question. ### What SQL looks like SQL reads almost like English. Using a small made-up library database, this query asks for the longer books, longest first: ```sql SELECT title, pages FROM books WHERE pages > 200 ORDER BY pages DESC; ``` It returned three rows: *Night Garden* (540), *The River Map* (312), *Paper Boats* (210). `SELECT` names the columns you want, `FROM` names the table, `WHERE` filters the rows, and `ORDER BY` sorts them. SQLite is a small database that lives in a single file on your own computer, with no server and no account. Python comes with a module for it, `sqlite3`, built in.^[27](#note-27)^ That's enough for everything in this chapter. ### Wrong answers you should be able to hear - **"The chart proves it."** Correlation, a cut axis, or missing data is doing the work. Say: "What would change your mind?" or "What else could explain it?" - **"I averaged the categories."** Averaging "favorite colors" or zip codes produces a number that means nothing. Say: "What would an average of those actually tell someone?" - **"The missing ones are zero."** A blank isn't a zero. Say: "Did that month use no water, or did nobody write it down?" - **"I'll just keep it in one big table."** Repeated names will drift. Say: "If Ana changes how she spells her name, how many rows do you have to fix?" - **"I made a chart; now what's the question?"** Tool first, question second. Say: "Put the question card on the table first." ### Your five-minute warm-up Take any receipt or bill in the house. On a sheet of paper, draw it as a table: what are the columns? What type is each one? What values are allowed? Is anything repeated that could live in its own table? Then say this chapter's opening question once, out loud: "What question are you asking — and could this data actually answer it?" That's your preparation. ## How to teach it this week This chapter is two weeks for most families: one for questions, dictionaries, cleaning, and charts; one for databases and SQL. Run each Hour inside the six steps of **The Computing Hour**. - **Specify.** The spec starts with the question card and the data dictionary. "Done" means the question is answered, or the student can say clearly why this data can't answer it. - **Predict.** "How many rows will survive cleaning?" "What will this query return?" Written down. - **Build and Test.** Small steps: read the file, print the first three rows, then clean, then count. For SQL, one clause at a time: `SELECT`, then add `WHERE`, then `ORDER BY`. - **Debug and Log.** Every cleaning decision goes in a change log; every surprise goes in the Debug Log with Expected/Actual. - **Review.** Re-read the question card. Does the chart answer *that* question? - **Ship and Explain.** "I specified… I predicted… It did… Next I'd change…" and "Help I used: …" **A word on whose data.** The student uses the family's own non-personal data (meter readings, a reading log, weather they recorded, the household's book collection) or public datasets from a library or government site. Data about siblings, friends, or strangers needs their permission first, and some of it shouldn't be collected at all. That's part of Family safety basics in **The Computing Hour**, and it's a good conversation to have before the first file is opened. **Monday: the question.** ### In-home — DATA-01 Question First - **Time:** 15 minutes - **Materials:** an index card, a pencil - **Safety and privacy:** pick a question about things, not people - **The fun:** asking something nobody in the house knows the answer to yet - **The skill:** writing a data question and the columns that would answer it - **The crumb:** a question card **How it goes.** On the front of the card, the student writes one question that has a checkable answer: "Which month do we use the most water?" "Do we finish shorter books faster?" "Is the backyard thermometer warmer than the forecast?" On the back, the columns that would answer it, and where the data would come from. Then they ask themselves: could this data actually answer the question, or only part of it? A question like "Are we a reading family?" can't be answered by a page count. "Did we read more pages in October than September?" can. **15–16:** you ask one question about the question: "How will you know when you've answered it?" **17–18:** the student writes two questions, one they think the data can answer and one it can't, and explains the difference. **Tuesday: the dictionary.** ### In-home — DATA-02 The Data Dictionary - **Time:** 15 minutes - **Materials:** paper, pencil, the question card - **Safety and privacy:** none needed - **The fun:** making rules before the mess arrives - **The skill:** name, type, and allowed values for each column, before collecting - **The crumb:** a data dictionary **How it goes.** One row per column: name, type, allowed values, and an example. For the water question: `date` (text in YYYY-MM-DD form, first of each month); `reading` (whole number, never smaller than last month's). Writing "never smaller than last month's" is the kind of rule that catches a typo later. At 17–18, add a line about how columns relate, the "logical relationships" in the standard: "usage is this reading minus last month's." **Wednesday: cleaning.** ### In-home — DATA-03 Clean It in Code - **Time:** 30 minutes - **Materials:** the editor, a small CSV file the student made or downloaded - **Safety and privacy:** never clean the only copy; work on a copy and keep the original - **The fun:** watching the program catch the messes you planted - **The skill:** reading a CSV, fixing spacing and case, dropping bad rows, logging what changed - **The crumb:** a clean file plus a change log **How it goes.** Start with the cleaning program from the parent section, or the student's own version. Before running, predict how many rows will survive. Then run it, compare, and read the log. Plant one new mess (a word in place of a number, a reading in the wrong column) and predict again. At the end, the program writes the clean rows to a new file, the way PY-04 Write a Report File taught in Chapter 2, so the original is never touched. **15–16:** a file of 10–20 rows. **17–18:** a public dataset of a few hundred rows, and a change log that says how many rows were dropped for each reason. **Thursday: the chart.** ### In-home — DATA-04 Chart That Answers - **Time:** 25 minutes - **Materials:** the clean data; graph paper, a spreadsheet, or a charting library - **Safety and privacy:** no names or faces in a chart that might be shared - **The fun:** cutting the axis on purpose to see what it does - **The skill:** one chart that answers the question, with an honest axis and a caption - **The crumb:** a chart plus caption **How it goes.** One chart. Its title *is* the answer ("June used the most water"). The axis starts at zero for bars. The caption says what the data can't show. Then, as an experiment, the student makes a second version with the axis starting at 400 and compares the two side by side. Same numbers; very different story. Neither is a lie on its face, but only one lets a reader judge the size of the difference. Charts can be drawn by hand on graph paper, made in a spreadsheet, or made in Python with a free charting library that's installed separately. Here's a short example using one widely used library, matplotlib: ```python import matplotlib.pyplot as plt months = ["May", "Jun", "Jul+Aug", "Sep"] units = [580, 880, 770, 490] plt.bar(months, units) plt.ylim(0, 1000) # the axis starts at zero plt.ylabel("Units used (meter reading change)") plt.title("June used the most water") plt.figtext(0.01, 0.01, "Jul+Aug is two months: the August reading is missing.") plt.savefig("water.png") print("saved water.png") ``` When we ran it, it printed `saved water.png` and made the image file. Notice where the honesty lives: the axis line, the label "Jul+Aug," and the caption.^[28](#note-28)^ **15–16:** hand-drawn or spreadsheet is fine. **17–18:** the chart includes at least two variables (usage and month, plus a mark for a vacation or a garden month), which is what the standard means by "multivariate." **Friday: who's missing.** ### In-home — DATA-05 Who Is Missing? - **Time:** 15 minutes - **Materials:** the dataset and the question card - **Safety and privacy:** none needed - **The fun:** finding the hole in your own data - **The skill:** sampling and coverage, meaning who or what the dataset leaves out - **The crumb:** a two-sentence note **How it goes.** The student writes two sentences: what or who this data leaves out, and how that could change the answer. For the water meter: "August is missing. The months we were on vacation used less, so a summer average would be too low." For a public dataset: "This survey only asked people with landlines." Chapter 8 comes back to this card, because it's exactly the question to ask of an AI system's training data. **The second week: databases.** Start on paper again. ## Practice that actually builds learning ### In-home — SQL-01 Tables on Paper - **Time:** 15 minutes - **Materials:** a messy one-big-table sheet (you can write it in five minutes), paper, colored pencils - **Safety and privacy:** first names only, made up - **The fun:** untangling a mess with arrows - **The skill:** rows, columns, keys, and why two tables beat one big one - **The crumb:** a paper schema **How it goes.** Write a table of library loans with a borrower's name, book title, pages, and date on every row, with Ana's name appearing three times and one book appearing twice. The student splits it into three tables (people, books, loans), gives each person and book an id, and draws an arrow from each id in the loans table to the table it points at. Then you ask: "Ana wants to be called Anna. How many rows change now?" One. ### In-home — SQL-02 First Queries - **Time:** 30 minutes - **Materials:** a small SQLite database file the student built from yesterday's paper schema, and either Python's `sqlite3` module or the `sqlite3` command-line tool - **Safety and privacy:** made-up data - **The fun:** asking a question and getting the answer in one line - **The skill:** `SELECT`, `WHERE`, `ORDER BY` on a small local database - **The crumb:** a query file with results **How it goes.** The student writes each query in a file, predicts the result (how many rows, which ones), then runs it. Start with `SELECT * FROM books;` to see everything, then narrow. The query from the parent section, long books longest first, is a good third query. Then the student writes their own: books under 100 pages; loans in October (`WHERE out_date >= '2026-10-01'`); people whose names start with A. Every result gets compared with the prediction. A query that returns zero rows when you expected three is a bug, not a quiet success. **15–16:** five queries from a list you agree on. **17–18:** the student writes the questions too. ### In-home — SQL-03 Join Two Tables - **Time:** 30 minutes - **Materials:** the same database - **Safety and privacy:** made-up data - **The fun:** putting the pieces back together - **The skill:** `JOIN` on a key; `GROUP BY` with `COUNT` - **The crumb:** a query file **How it goes.** A join answers "who borrowed what?" by following the arrows from the paper schema: ```sql SELECT people.first_name, COUNT(*) AS loans FROM loans JOIN people ON loans.person_id = people.person_id GROUP BY people.first_name ORDER BY loans DESC; ``` On the small library database, it returned `Ana 3` and `Ben 2`. Then the good question: the people table also has Cal. Where is Cal? He has no loans, so the join had nothing to match him to. That's not a bug in SQL. It's a "who is missing?" moment, and a perfect DATA-05 echo. (A different kind of join can include him with a count of zero; the student can look it up in the SQLite documentation as a stretch.) Then the classic mistake, on purpose: leave off the `JOIN … ON` and list both tables, `SELECT COUNT(*) FROM loans, people;`. On our database it returned `15`: every one of the five loans paired with every one of the three people. When a join returns far too many rows, the key condition is missing or wrong. **17–18:** joins across all three tables. **Ready 16:** a 16-year-old who drew the paper schema confidently can start here. ### In-home — SQL-04 Python Talks to SQLite - **Time:** 35 minutes - **Materials:** the editor and the database file - **Safety and privacy:** this card teaches the safe way first; Chapter 7 shows why, on the student's own toy app - **The fun:** a little program anyone in the family can use - **The skill:** using Python's built-in `sqlite3` with parameterized queries - **The crumb:** the program file **How it goes.** A short program asks for a first name and lists that person's loans: ```python import sqlite3 conn = sqlite3.connect("lib.db") name = input("First name: ") rows = conn.execute( "SELECT books.title FROM loans " "JOIN people ON loans.person_id = people.person_id " "JOIN books ON loans.book_id = books.book_id " "WHERE people.first_name = ?", (name,), ).fetchall() for (title,) in rows: print(title) print(len(rows), "loans") conn.close() ``` Typing `Ana` printed *The River Map*, *Night Garden*, *Paper Boats*, and `3 loans`. The `?` is the important part. It's a **parameter**: a placeholder that `sqlite3` fills in safely with whatever the user typed, as data, never as part of the SQL itself. When we typed the classic trick input `Ana' OR '1'='1`, the program printed `0 loans`, because no one's first name is literally that string. Building the query by gluing the user's text into the SQL string would have let that input change the question. Parameterized queries are the default from the first day, and Chapter 7 shows the difference on the student's own toy login form, under the family security rule.^[27](#note-27)^ **17–18 only.** ### In-home — DS-03 Nested Data on Paper - **Time:** 15 minutes - **Materials:** paper, pencil - **Safety and privacy:** none needed - **The fun:** finding a value three levels down - **The skill:** drawing a list of dictionaries (records) and tracing access paths - **The crumb:** a diagram **How it goes.** You met this card in Chapter 2. This week, draw the loans as a Python list of dictionaries, one dictionary per row, and trace `loans[1]["book_id"]` with a pencil. Then compare with the table. A database table and a list of dictionaries are two drawings of the same idea, and a row from `sqlite3` is easy to turn into either. ### Out-of-home — OUT-02 Library Computer Hour - **Time:** 50 minutes - **Materials:** a library card, a USB drive or the student's own cloud folder - **Safety and privacy:** log out of everything; save to your own drive; don't leave files on the public computer - **The fun:** a librarian who knows where the data lives - **The skill:** a Computing Hour on a public computer, logging out and saving to your own drive - **The crumb:** a file saved in two places **How it goes.** You met this card in **The Computing Hour**. This week, borrow it for data. Many public libraries offer access to local and government datasets, and librarians are often delighted to help find one. The student asks one question at the desk ("Where would I find data about rainfall in our county?"), downloads one small public dataset, writes its data dictionary on the spot, and saves it in two places. At home, the Question First card decides whether it's worth cleaning. ### Talk box (this chapter) **Opening:** "What question are you asking — and could this data actually answer it?" **Follow-ups:** 1. **Prediction:** "Before you run it, how many rows do you think will come back?" 2. **Evidence:** "Which rows make you say that? Show me in the table." 3. **Location:** "Where in the data would the answer live, and which column?" 4. **Change:** "If the axis started at zero, what would the chart look like?" 5. **Revision:** "What else could explain it, and what data would tell us?" **How to wait.** Count to five in your head. When the question is about code on the screen, let them read as long as they need. Look at the code, not at the student. **What a stuck silence usually means.** Often that the question card was vague, so there's no way to know if the data answers it. Go back to the card. Sometimes it means the student made the chart before the question and is now trying to find a question that fits. Sometimes it means they've just seen the hole in their data and don't want to say so. Make it easy: "Missing data is a finding. Write it down." **Don't say / say instead.** Don't say "That's a nice chart"; say "What's the one sentence this chart proves, and what can't it show?" ### An incorrect example to diagnose Hand the student this, labeled as a misleading chart: a bar chart of the four months where the vertical axis starts at 450. June's bar stands more than ten times as tall as September's. Ask: "Read me the actual numbers." June used 880 units and September 490: under twice as much. Then: "Who might draw it this way on purpose? Who might do it by accident?" Both happen. Spotting it is the skill. ### Mixed practice Once each card has been done once, mix the stages. Give the student a small dataset with no instructions and see whether they reach for the question card first. Alternate a Python cleaning Hour with a SQL Hour on the same data. Keep the monthly AS-01 Cold Trace from Chapter 1, and once a week ask, from memory, what `WHERE` and `GROUP BY` do. At the end of the second week, AS-03 Explain Your Code works well with a query: the student explains each clause of a join. ## For the student Data is everywhere, and most of what people say about it is wrong. Not because they're lying, usually, but because they started with a chart instead of a question. This chapter teaches you to start in the right place. **Question first.** Before you open a single file, write one question on a card. Make it one you could actually answer: "Which month do we use the most water?" not "Are we wasteful?" On the back, write which columns would answer it. **Dictionary second.** For each column: name, type, allowed values. "Reading: whole number, never smaller than last month's." That one rule will catch typos for you later. **Then clean it, in code, with a log.** Here's the heart of a cleaning program: ```python text = (row["reading"] or "").strip() if not text.isdigit(): log.append(f"dropped {date}: reading was {text!r}") continue ``` `.strip()` removes stray spaces. `.isdigit()` checks that what's left is a whole number. Anything that fails is logged, not silently deleted. When we ran this on a file with "n/a" in it, the log said `dropped 2026-08-01: reading was 'n/a'`. That log is how a stranger can trust your answer. **One honest chart.** The title is the answer. The axis starts at zero (for bars). The caption says what the data can't show. Make one version with the axis cut off, once, just to see how much it changes the story. You'll never read a news chart the same way. **Databases.** When data grows, it moves into tables that link by keys. A loans table doesn't repeat Ana's name; it just says person 1 borrowed book 3. A query puts it back together: ```sql SELECT title, pages FROM books WHERE pages > 200 ORDER BY pages DESC; ``` Read it out loud: select the title and pages from books, where pages are over 200, sorted by pages, biggest first. SQL is one of the most widely used languages in computing, and you can learn the core of it in a week. **Try this today.** Write a question card about something in your house that isn't about people (books, weather, water, electricity, a garden). Write the data dictionary. Collect or find ten rows. Clean them in code with a log, even if they're already clean (plant one mess to make sure your code catches it). **Explain it back.** Pick one cleaning decision you made and explain it to a parent: what was wrong, what you did, and why that was better than the alternatives. Was dropping the row better than guessing a value? Why? Then explain a join: which key connects which tables? **This part is hard for everyone.** Messy data. Real data is always messier than you expect. Spaces, typos, blanks, a date written three ways, a number in the wrong column. Professionals spend a large share of their data time cleaning. It isn't the boring part before the real work; it *is* the real work, and the log is what makes it trustworthy. **About "proof."** Data rarely proves anything. It supports, or it doesn't. If two things go up together, ask what else could explain both. If someone shows you a chart, ask what's missing from it. And if your own data has a hole in it, say so in the caption. That's not weakness. That's what makes people believe the rest of your chart. **If you're 17 or older:** connect Python to SQLite (SQL-04) and use parameterized queries, with the `?` placeholder, every single time a query includes anything a user typed. Never glue user input into a SQL string. Chapter 7 will show you why, on your own toy app. Also try a join across three tables, and explain what would happen if you got the key condition wrong. (Try it. On a five-loan, three-person database, the wrong version returns 15 rows.) **A worked cleaning step.** Picture one row that reads `2026-07-01, 11690 ` with a space before and after the number. Without `.strip()`, the text is `" 11690 "`, and `.isdigit()` says no, because spaces aren't digits. Your program would drop a perfectly good reading and log it as bad. With `.strip()`, the text becomes `"11690"`, passes the check, and becomes the number 11690. One method call is the difference between a missing July and a correct one. That's why you predict how many rows will survive before you run the cleaner: if your prediction is five and the program says four, you've found something. **A query to write today.** Once you've built a small database, write this one yourself before looking anything up: "Which books have more than 200 pages, longest first?" Then change one clause at a time. Take off `ORDER BY` and predict the order. Change `>` to `<`. Add a second condition with `AND`. Each change is one prediction and one run, exactly the loop from Chapter 3. Save the queries in a file with the results pasted under each one; that file is your crumb, and it shows a stranger exactly what you asked and what came back. **Challenge.** Build a small database of three tables from your house (books, people with first names only, and loans; or plants, beds, and waterings). Write a join that answers a real question, then find the row the join leaves out and explain why it's missing. Write it up in three sentences: the question, the answer, and what the data can't tell you. **What to save:** your question card, data dictionary, original and cleaned files, change log, chart with caption, query file, and Debug Log pages. Save them in two places. ## If it isn't clicking **The chart comes before the question.** It's a tool-first habit, and the tools make it easy. The fix is physical: the question card goes on the table, face up, before the laptop opens. If the chart's title isn't an answer to the card, it's not done. **Joins return too many rows.** The keys aren't clear yet. Back to SQL-01 on paper, with arrows. Ask the student to trace one loan row by hand, from its `person_id` to the right person and its `book_id` to the right book. Then write the `ON` condition from the arrow. **"The data proves…"** Cause and correlation have merged. Ask "What else could explain it?" and wait. Then ask what data would tell the two explanations apart. This is a habit, built one question at a time, not a lecture. **Cleaning feels pointless.** The data looked fine. Plant three messes in a copy and let the student's code find them. Then find a public dataset with real ones. When the student sees their first real "n/a," the log stops feeling like busywork. When they ask for rescue, the order is the same as ever: ask → wait → hint → short demo on your own copy → hand it back. If data becomes the student's passion, a statistics course, a co-op data project, or a dual-enrollment class (Chapter 9) can take it further, and "Data Science" can become its own transcript line. ## Tools, including AI Python's `csv` and `sqlite3` modules are built in. The `sqlite3` command-line tool is a small free download if your student wants to type SQL directly. Spreadsheets are fine for looking at data, and for charts at 15–16, as long as the cleaning happens in code, where it's logged and repeatable. A charting library such as matplotlib is a free extra, installed separately. SQLite's own website has a full, readable reference for SQL.^[27](#note-27)^ The AI rules are the ones in the AI box in **The Computing Hour**. Here's what differs. AI chat tools are fluent at writing SQL and at describing what a chart "shows," and both are places where confident output can be quietly wrong. At 15–16, chat help may explain what a query clause does, after the student has written their own prediction. No personal data, family data, or anyone's names go into a chatbot, ever; that includes pasting a dataset in to "clean it for you." The editor coding assistant stays off through 16 and for every check. At 17, on the one named project, any suggested query is run against a small table where the student already knows the right answer before it's kept. Check the current terms of any tool before your student uses it. ## What "done enough" looks like Move on when most of these are "seen," a few are "growing," and none of the first three is "not yet": - [ ] Writes a question card with a checkable question before opening any data (DATA-01) - [ ] Writes a data dictionary with name, type, and allowed values for each column (DATA-02) - [ ] Cleans a file in code, with a change log, without touching the original (DATA-03) - [ ] Makes one honest chart with a title that answers the question and a caption that names a limit (DATA-04) - [ ] Writes two sentences about who or what the data leaves out (DATA-05) - [ ] Splits a one-big-table mess into linked tables on paper, with keys (SQL-01) - [ ] Writes `SELECT`, `WHERE`, and `ORDER BY` queries and predicts their results (SQL-02) - [ ] **AS-03 Explain Your Code:** explains a cleaning program or a query, line by line or clause by clause. You write one line about how it went. - [ ] **17–18 (ready 16):** writes a join with `GROUP BY` and explains the key (SQL-03); **17–18:** uses `sqlite3` from Python with parameterized queries (SQL-04). **Placement.** Place by skill, not birthday. A 15-year-old who writes question cards and cleans with a log is ready for Chapter 6. A 17-year-old whose charts still come before questions needs another week here. If your student loves this chapter, let it run long; a data-heavy semester is a real course. \newpage # Chapter 6 ## Building for People: The Web, the Command Line, and Git ![A web page wireframe sketch beside a dark terminal window of short colored lines and a branching line diagram on an index card — still life, no people, no logos, no readable text.](art/ch06-opener.jpg){width=100%} ## Why this matters Here is an illustration, not a real family. Picture a fifteen-year-old building a one-page site for his grandmother's pancake recipe. He's proud of the design: a pale gray font on a cream background, a custom-drawn "button" that changes color when the mouse is over it. Then his grandmother tries it. She can't read the gray text without her glasses. She doesn't use a mouse; she uses the keyboard on her tablet stand. She presses Tab to reach the button, and nothing happens, because the "button" isn't really a button at all. It looks like one. It isn't one. He didn't do anything careless. He built for the person he knew best, which was himself. This chapter is about building for someone else. Software is for people. The web is how most software reaches them, and every choice on a page (the size of the text, the order of the headings, whether a button is a real button) decides whether a real person can use it. The chapter has three parts, and they belong together. **The web**: HTML for structure, CSS for appearance, JavaScript for behavior. **The terminal**, or command line: typing commands to the computer instead of clicking, which is where programmers do much of their daily work. And **Git**: a tool that keeps the history of every saved change. Each saved change is a **commit**, with a message saying what changed and why. Git is how programmers keep a project's story, go back when something breaks, and work together without overwriting each other. This is also the chapter where your student's work starts to look like a professional's. A small site, built for a named user, tested with the keyboard, kept in a repository with real commit messages and a README a stranger can follow, is a serious piece of work. It's portfolio material. If the year leans heavily this way, it can even become its own transcript line: **Web Development**. Chapter 9 explains how to describe it. One honest note: "every programmer uses X" is never quite true. Git, the terminal, and the web's three languages are *widely used*, across most of the industry and in college courses. That's reason enough to learn them, without pretending they're universal. ## For the parent: understand it yourself You don't need to build websites to teach this chapter. You need to be a demanding first user, know what a good commit message looks like, and be able to say "Try it with the keyboard only." You'll have all three by Friday. **The everyday picture.** A house has a frame, paint, and wiring. HTML is the frame: walls, rooms, doors, which room is the kitchen. CSS is the paint and furniture: colors, sizes, where things sit. JavaScript is the wiring: press a switch and a light comes on. You can have a frame with no paint; you can't paint a house that has no frame. And a door that's only painted on the wall isn't a door. **The precise picture.** The national high-school standards from the Computer Science Teachers Association put the goal in one line: "Design a computing technology using human-centered design principles."^[29](#note-29)^ *Human-centered* means you start with a person, not a feature list. Who is this for? What will they see, do, and need first? That's this chapter's talk-box opening, and it's the first line of every web spec. ### What a page looks like underneath Here's the whole recipe page, cut down to fifteen lines: ```html Nana's Pancakes

Nana's Pancakes

  • 2 cups flour
  • 2 eggs
  • 1 1/2 cups milk

``` Every piece in angle brackets is a **tag**, and most come in pairs that wrap content: `

` starts the main heading and `

` ends it. The words are chosen for meaning, not looks. `
` says "this is the main content." `
    ` and `
  • ` say "this is a list." `