Capstone: Build It, Prove It, Hand It Over

Anybody can get something working while they are standing next to it. This class is about the other three things: proving it works when you are not, writing it down so somebody else can run it, and being able to defend every line of it whoever wrote the first draft.

What "done" means#

A thing that works on your laptop while you are watching it is not done. It is the first of four steps, and the other three are where the value is.

1. It works. The normal case, on real data, in front of somebody else. This is the step everybody does and the only one most people count.

2. It survives. Your ugly input does not crash it, does not silently drop rows, and does not produce a confident wrong answer. It reports what it could not handle, by name, with the row number.

3. It fails in a way you chose. When the file is missing, the network is gone, the value is out of range or the power went halfway, it does the thing your five sentences said it would. Not the thing that fell out.

4. Somebody else can run it. Without you. From the README. On a machine that is not yours.

You are assessed on all four, and the marks are weighted the way the industry weights them: the first is worth the least.

The four things being assessed#

Does it do the job#

The narrow question, and the easy one. It does what the five sentences said. It is worth having a demo you can run in ninety seconds without narration.

Can you defend every line#

You will be asked about a specific line, chosen by me, and asked what it does, what it assumes, and what happens if that assumption is wrong. It does not matter who or what wrote the first draft. A model, a colleague, a forum post from 2013 and your own hands are all the same answer: you shipped it, so you can explain it.

If the honest answer is "I do not know what that line does", that is a finding rather than a disaster, and it is worth more said out loud now than discovered later. The correct move at that point is to simplify until you do know, which is a professional instinct and not a retreat.

Does it behave when things go wrong#

I will break it. Rename the input file. Feed it the row with the empty address. Pull the network. Pull the power halfway through a write. Send the cue twice. What I am watching is not whether it survives everything, because it will not. It is whether what happens is what you said would happen, and whether it says something useful when it cannot continue.

Could somebody else take it over#

Ten lines of README: what this is, how to run it, what it assumes, what it does when it fails, who to ask. A repository with commits whose messages mean something in six weeks. Constants named and in one place. A note saying which parts were generated and what you verified them against.

A tool nobody else can run is a tool that exists only until you are unavailable, and you will be unavailable exactly when it matters.

Choosing a project#

Small and finished beats ambitious and half working, every time and in every year of this course. The best capstones are boring and real.

Projects that have worked:

• A patch checker. Reads the real fixture export, reports address clashes and any fixture whose footprint runs off the end of its universe, with both names and the overlapping range.
• A converter. Takes what one piece of software exports and produces what another one imports. Endlessly useful, entirely mechanical, and every department has one they need.
• A prop with a defined failure. Sensor to decision to actuator, on a cue, with a timeout and a safe state you can demonstrate by pulling a cable.
• A report generator. Turns a cue list or a schedule into a printable page, so a change to the source regenerates everything downstream instead of somebody retyping it.
• A rehearsal timer or a call sheet screen on a Pi, starting on boot, that survives a power cut.
• A file discipline tool. Renames or checks a media folder against a naming convention, reports what does not match, and never touches anything without --dry-run first.

Projects that have gone badly, every year:

• Anything with a deadline outside this room. A capstone that has to work for a real show next week is a capstone you will cut corners on, and the corners you cut are steps two to four.
• Anything you have to learn a whole new framework for. The framework becomes the project.
• Anything where the interesting part is the hardware you have not got yet.
• "An app." If you cannot say what it does in five sentences, it is not scoped.

The test: could you finish it badly in one afternoon? Then you can finish it well in three.

Making it survive the ugly input#

This is Lab B and it is the block that separates a script from a tool. The method is not clever, it is just done rather than skipped.

Write down what you are given, then break each promise in turn. For every input:

That last row has a name worth knowing: something safe to run twice is idempotent, and a tool that is safe to re-run is worth roughly double one that is not, because in production everything gets run twice at some point, by somebody who is not sure whether the first one worked.

And the rule that outranks all of this: anything destructive gets a dry run first. Print what it would do, run it on a copy, then run it for real. One flag, one line, and it is the difference between a mistake and an incident.

The standard, in miniature#

Thirty minutes, and it is the capstone in one function. A call sheet: normal case, two ugly cases, and one specified failure. The two rules that matter are the last two, and both are places where the easy behaviour, dropping the row, produces a document that looks correct and is not.

If you can pass all six of these, you know what the marker is looking for. If you cannot, the thing to fix is not your code, it is your instinct about which inputs are worth defending against, and that instinct is the actual subject of this course.

Breaking somebody else's#

Lab C, twenty five minutes on somebody else's project, and it is the most useful half hour in the class for both of you.

You are not looking for style. You are running the four questions on code you have never seen, on a clock, which is exactly the situation that made this course exist.

The order that finds things fastest:

1. Read the README and try to run it from that alone. If you cannot, that is finding number one and it is the most valuable one.
2. Find everything that writes or deletes. Read those lines character by character.
3. Feed it the empty field, the duplicate and the last row.
4. Take away something it assumed: rename the input, unplug the network, delete a folder it expected.
5. Run it twice.
6. Only then read the logic in the middle.

Write down what you did and what happened, in order. Hand that back. A finding written as "it crashed when I gave it an empty address, here is the traceback and the row" is worth an hour to the author; "it seems a bit fragile" is worth nothing to anybody.

Receiving this well is part of the assessment too. A finding is somebody spending their time making your thing better. The professional response is a question and a commit, not a defence.

The handover#

Lab D, and the part that gets skipped in every course and every production.

The README, ten lines. What this is. How to run it, as a command somebody can copy. What it assumes: the Python version, the file it expects, the address it talks to. What it does when it fails. Who to ask.

The commits. Messages that mean something in six weeks, which is when they get read, which is during a technical rehearsal by somebody looking for the change that broke it. That person may well be you.

The failure behaviour, written down as a sentence with a number in it. "If no cue arrives for two seconds it goes to its safe state, which is off. Two seconds was chosen because the console's own heartbeat is one second and one missed heartbeat should not fire the effect."

What was generated and what you verified. Not because it is shameful. Because the next person needs to know which parts had a human's full attention and which were checked against three cases.

And for anything physical, the one page in the case. What it is, its ratings, its pinout, its behaviour on power-up and on loss of control, its indicator codes, and a phone number. This is the same sheet Electronics for Theatre asks for, because it is the same case and the same 23:40.

The last exercise#

Give your project to somebody who has never seen it. Say nothing. Watch them read the README and try to run it.

Do not help. Do not explain. Write down every place they hesitate.

That list is the real result of this class. Everything on it is something you knew and did not write down, and every item is an hour of somebody's time on a production where you are not in the building.

If you want a bigger project than four hours#

Some people want the capstone to be the start of something rather than the end of a module. Three routes, in increasing order of how much of your own time they will eat.

The model box. Wire a 1:25 white card model as a complete show system: pixels on booms, an ESP32 taking Art-Net from a free desk, a servo against a limit switch, a Pi playing sound on OSC. Between HK$900 and HK$2 600, five stages that each stop cleanly, and every layer of a real building at a scale where breaking it costs an afternoon. The full build is here, and stages one to three are what Class 5 taught you.

A tool for a department that keeps asking for one. Find the thing somebody in this building does by hand forty times a production. Do the break-even arithmetic honestly, and if it comes out positive, build it, hand it over properly, and watch somebody use it without you in the room. That last part is worth more than the code.

A Companion module, or a bridge nobody has written. Two products in this building that should talk to each other and do not. Check Bitfocus Companion first, because it very often already does it and choosing that over your own script is the mature answer. When it does not, the module is a smaller and better-supported job than a standalone tool, and somebody else gets the benefit of your afternoon.

All three are assessed the same way, on the same four things, and the fourth one is still the handover.

Where this course leaves you#

Twenty four hours. You should now be able to:

• Read a program and say what it holds, does, assumes and does when it is wrong, in a language you do not know, at speed
• Write a small one that does a real job, on real data, with the failures named
• Choose a data shape on purpose and know what it costs at scale
• Keep the work so it survives you, and find a fault by narrowing rather than guessing
• Direct a model to write the draft and verify it well enough to put your name on it
• Put code on a board that makes a physical thing happen, with a safe state you specified first
• Say which notation and which language a job wants, and why the boring answer is usually right

One of those courses you have already done, and two of them are for other rooms:

The first two rows are the whole of what this school gave you on this subject, sixty four hours and twenty four, and between them they cover the hardware and the software with almost nothing said twice. The third is somebody else's curriculum and is there if you ever need what it knows. The fourth is the one to take next if the protocols were the part that held your attention.

The same discipline every time: establish what is actually true, at the layer where the question can be answered, and never accept a comfortable story instead of a measurement. The how they relate page says which one goes deepest on what, and where to go next is what to read when all four stop being enough.

Numbers from this class#

Self test with model answers

Answer it yourself first, out loud or on paper, then open the answer. Reading the answer without attempting the question teaches you almost nothing.

1. 1A colleague says their tool is finished because it works. Name the three steps they have not done, and say which is worth the most.
2. 2I point at a line in your project that a model wrote and ask what it does. What is the professional answer, and what is the professional answer if you genuinely do not know?
3. 3Give four ways to break a tool that reads a fixture export, and say what a good response to each looks like.
4. 4Why is "could you finish it badly in one afternoon" a good test for a capstone scope?
5. 5You hand your project to somebody who has never seen it and they hesitate six times. What have you actually learned?

Note. These are model answers, not the only correct ones. If yours differs and you can defend it with the arithmetic and a measurement, that is worth more than matching the wording.