Specifications and design: decide what the build must do
Now we fix the problem at its root. In the Code Literacy lesson, you read a program that ran without an error and printed 3000. The organiser needed the total received, which was 2,500. Nobody had written down which total they meant.
In this lesson, we'll close that gap before any code exists. We'll:
- find the question a short request leaves open;
- write down, in plain words, what the program must do, what it must not do, and how we'll check it;
- turn each requirement into a check with a known answer;
- make one design decision about where a rule should live.
Why it matters: whoever builds the work, you or an AI, has to make every choice your request leaves open. Writing it down first lets you make the important choices yourself, in words you can check the result against.
Which question did the request leave open?
The first request was one line: show this month's committee total. It sounds complete, until you remember the committee's record. Each of the three members is due 1,000 rupees. Member C has paid only 500 so far.
So "total" has at least two sensible meanings:
| Meaning | Calculation | Result |
|---|---|---|
| Total due this month | 1,000 × 3 members | 3,000 |
| Total received | 1,000 + 1,000 + 500 | 2,500 |
A careful AI assistant may well ask you which one you mean. That only helps if you know the answer and can say it exactly. If you reply "just the total", you've handed the decision back without making it.
A request becomes useful when it answers the questions that change the result. Here, the question that matters is received or due?
Write it down in plain, exact words
A specification, or spec, is a written statement of what you want built, and what must not change, agreed before the work starts. It doesn't need special software or a fixed template.
From now on, we'll call our program the committee report, because it reports totals to the organiser. For it, I would write this spec:
Purpose
Show the organiser how much money is recorded as received this
month, and how much is still due.
Inputs
The amount recorded as received from each of the three members.
Each member is due 1000 this month.
Required output
Two lines:
Received: <total received>
Still due: <total due minus total received>
Boundaries
Use only the invented example amounts on this page.
Read the amounts; never change or delete a stored record.
Acceptance criteria
1. Received 1000, 1000 and 500 -> "Received: 2500" and "Still due: 500"
2. Received 1000, 1000 and 750 -> "Received: 2750" and "Still due: 250"
Each part answers a different question:
- Purpose says who the work is for, and what they need to know.
- Inputs say what information the program receives.
- Required output says what a correct result looks like, down to the exact words.
- Boundaries say what the work must not do. A requirement is anything the work must satisfy; boundaries are the requirements that forbid something.
- Acceptance criteria are the checks that decide whether the finished work is accepted. The arrow
->means "should give".
Notice the word received. It appears in the purpose, the inputs and the output. That's on purpose: it is exactly where the first program went wrong.
Turn each requirement into a check with a known answer
An acceptance criterion pairs a situation with the result you expect, and you write it before you see what the program does. You work out the expected answer yourself, from the purpose, never from the program's output.
For the first criterion: 1,000 + 1,000 + 500 is 2,500 received. The total due is 1,000 × 3, which is 3,000. So 3,000 − 2,500 leaves 500 still due.
The second criterion changes one input on purpose. If Member C pays 750 instead, the report should say 2,750 received and 250 still due. A program that always printed 2,500 would pass the first check and fail this one. That's why one example is rarely enough.
You'll often see checks like these written as given a situation, when something happens, then a result is expected. Martin Fowler explains this pattern, and many testing tools use it. The arrows in our spec say the same thing more briefly.
Why design comes before the code
A spec says what must be true. Design decides how the work is arranged so that it can be true: which parts exist, which part does each job, and where each rule lives.
Our report is one small program, so its design is short. The three amounts received are inputs. The amount due per member is a fixed value for this month. The program works out two totals and shows them.
Now remember the bigger app from the architecture lesson. Suppose the member page, the organiser page and the export all need "still due". I would put that calculation in the backend, in one place, not copy it into each screen. Then a change to the monthly amount has one place to check.
Some rules are so important that they belong in the spec itself, like never change or delete a stored record. But a spec is a request: writing a rule down doesn't make a program obey it. In the coding agents lesson, you saw the difference between asking a tool not to do something and setting a permission that stops it. You still have to check the result.
Write a spec from memory
Without looking back, list the five parts of the committee spec, and say in one sentence what each one is for.
Then write a third acceptance criterion: Member C has paid nothing yet, and the other two have paid 1,000 each. Work out both expected lines yourself, using the calculations above. The next lesson shows the answer.
In the next lesson, we'll run a program written from this spec and check it against these criteria. We'll also see what happens when the first program faces the same checks.