Week 5 · Monday, September 28, 2026 · Room D-221

The best code you write this week is not Python.

Last week you built from finished diagrams and finished code. From now on, most of what you build starts as a blank page. Today you learn the two tools that turn a vague idea into something a pair can build and a grader can check: requirements that say what, and pseudocode that sketches how. Then you use both, on the bench, with your kit.

1 h theory 2 h lab Bring the breadboard kit

What happens today

Theory · first hour

Specifying and sketching

What makes a requirement testable instead of decorative, how pseudocode captures logic without syntax, how to prove a design on paper with a trace table, and where flowcharts and state diagrams fit, including their family ties to the sequence charts you know from automation.

Start with Requirements →

Lab · two hours

A reaction timer, spec first

One worked example runs through the whole day: a reaction-time game on your LED and button. You will write its requirements, sketch and trace its pseudocode, translate it to Python, verify it against its own spec, and then design your own variants the same way. The spec files go in the repository beside the code.

Jump to the Design lab →

In the course outline

This is Week 5 of 420-302-VA, the second week of the Python thread. The midterm (Week 7, October 19) covers Weeks 1 to 6, and reading, writing and tracing pseudocode is exactly the kind of thing it can ask on paper, where no interpreter will save you. Looking further: Assignment 2 (Week 8) hands you a requirements list you must satisfy, and the term project hands you nothing, you write the requirements yourselves, and they become part of the graded documentation. This week is where both skills start.

Why design before code

Last week's scripts were small enough to improvise: type, run, adjust, done. That method has a ceiling, and you will hit it the first time a program has more than one thing going on at once. Watch what happens to the reaction timer if you improvise it: you code the happy path (light comes on, press, print time), it works, and then someone presses before the light. Now the "wait" part needs to watch the button too, the timing variable is in the wrong place, and the patch touches every line you wrote. The problem was not your Python; it was that nobody ever wrote down that false starts had to be handled.

Both paths loop; only one converges. Designing does not remove mistakes, it moves them earlier, where changing a sentence is cheaper than rewiring a program. This is the oldest lesson in software engineering: the later a defect is found, the more it costs to fix.

Design earns its keep four ways in this course specifically:

Pairs need a shared picture. "Build the timer" splits badly; "you make R1 to R3 pass, I take R4 and the docs" splits cleanly. Requirements are how a team divides work without dividing the system.
Logic can be reviewed before syntax exists. Your partner can find the flaw in six lines of pseudocode in one minute. Finding the same flaw inside running Python takes ten, plus the debugging detour.
"Done" becomes checkable. A testable requirement is a finish line. Without one, projects end in "it mostly works", which is not a sentence graders or clients accept.
The thinking survives. Specs and pseudocode are documents. They go in the repository, they explain the code to a stranger, and the project's documentation standard, a third party could rebuild it, is largely made of them.

Why this course teaches it now

You just felt the gap

Week 4's practice ladder got harder exactly where the logic got harder, not where the Python did. Double-blink acknowledge defeated more people on paper than on the keyboard. Design tools are the answer to that specific pain, taught while the pain is fresh.

The programs are about to grow

Week 6 adds classes, Week 8 a second computer, Week 9 a network between them. Improvisation that barely held for twenty lines does not hold for two hundred across two machines. The habit has to be in place before the growth, not after.

It is the profession's split

In automation work, someone writes the functional description and someone implements the control program, often the same person on different days. Requirements and design documents are the industry's interface between those days. This week you practise both roles.

Three ideas you will reuse for the rest of the course

What before how

A requirement states what the system must do, observably, without choosing the implementation. Keeping the two apart lets the what be agreed on, tested against, and kept stable while the how evolves.

If you cannot test it, you have not said it

"Responds quickly" is a wish. "Reports the time within 100 ms" is a requirement, because a test can pass or fail it. Every requirement you write this week comes with its own way of being checked.

Trace before you run

You can execute a design in your head, line by line, with a trace table tracking every variable. It is slower than the interpreter and infinitely better at teaching you why, and it works in an exam room.

What you will be able to do by the end of the week

Tell a requirement from an implementation choice, and a functional requirement from a non-functional one.
Write numbered, testable "shall" requirements for a small system, with acceptance criteria, and repair vague ones.
Write pseudocode in this course's conventions, at the right level of detail, mapping cleanly onto Python's constructs.
Desk-check a design with a trace table and catch a logic error before any code exists.
Read and draw simple flowcharts and state diagrams, and choose between them and pseudocode deliberately.
Run the full cycle on hardware: requirements → pseudocode → trace → Python → verification against the requirements, with the design documents committed beside the code.

Words you will hear all day

Term	Plain meaning	Common mix-up to avoid
Requirement	A single, testable statement of something the system must do or a quality it must have.	Not a feature wish or a design choice; "uses gpiozero" is a decision, not a requirement.
Functional requirement	A behaviour: given this situation, the system does that.	Distinct from non-functional qualities like speed, accuracy or reliability.
Non-functional requirement	A measurable quality of how well it behaves: timing, accuracy, usability, constraints.	"Non-functional" does not mean unimportant; it means it is not a behaviour.
Acceptance criterion	The concrete check that decides whether a requirement is met.	If you cannot write one, the requirement is not finished.
Specification (spec)	The collected requirements for a system, written down and agreed.	A living document, updated deliberately; not a first draft frozen forever.
Pseudocode	Structured plain language describing logic: real structure, no language syntax.	Not "vague code"; it is exact about logic and silent about syntax.
Trace table (desk check)	Executing a design by hand, one row per step, one column per variable.	Tracing what the text says, not what you meant; the gap between the two is the bug.
Flowchart	A diagram of control flow: boxes for actions, diamonds for decisions, arrows for order.	Good for branching flow; clumsy for data details, where pseudocode wins.
State / state diagram	A named mode the system can be in, and the events that move it between modes.	State is remembered in variables; a state diagram is the map, not the memory itself.
Edge case	An input or timing at the boundary of what you expected: too early, zero, twice, never.	Edge cases are found by asking the spec questions, not by hoping the demo avoids them.

Where this fits in the course

Week 4 · Sep 21

Python and GPIO

First code, first circuit. The constructs you learned, variables, if, loops, functions, are exactly the vocabulary pseudocode abstracts.

Week 5 · Sep 28 · this hub

Requirements and pseudocode

Design before code: testable requirements, traceable pseudocode, flowcharts and state, practised on a system you specify yourselves.

Week 6 · Oct 6 (Tuesday, Monday schedule)

Object-oriented programming

The functions you design this week get organized into classes: state and behaviour packaged together, the shape of every gpiozero object you have already used.

Working at home

This is the one week where the core skill needs no hardware at all: requirements and pseudocode are paper tools, practicable on the bus. Spec something from your daily life, a microwave's timer logic, a thermostat, an elevator's door, then pseudocode it and trace it. If you have a home Pi setup (Week 2, working at home), the whole design lab reproduces; if not, every design exercise can still be traced on paper and the Python tested later. The Resources page links practice material for both halves.