103 How the work turns — vocabulary and procedure

103.1 Without names, the same thing gets called different things#

First, the words of this chapter in one place. Each returns later with something real beside it, so skimming now is enough.

★ None of these is the name of a tool. Tools differ from project to project, but the places they are called from are the same. Learn the words and even an unfamiliar repository becomes readable.

103.2 The fixture — the ground a test stands on#

Running one test needs provisions: an input to read, an answer to compare against, a temporary folder made in advance, data holding known values. That bundle of provisions is the fixture.

chapter 102′s golden demonstration already had them. They simply went unnamed.

★ A fixture has one condition — it must be the same every time. If yesterday and today differ, then when a test fails you cannot tell “was the code wrong, or did the provisions change”. At that moment the test stops being a thing that gives answers and becomes a thing that adds one more question.

So there are things that must not serve as fixtures.

The word’s root is that same property. A lamp or a pipe fixed into a building is called a fixture, and the sense of not moving about, always being there is what carried over into testing.

103.3 The witness — a check is a defect’s gravestone#

Say you have fixed a bug. What do you leave behind at that spot? Leave nothing and the bug comes back — people change, code is edited, and nobody knows the story any more. A defect that has come back is called a regression.

There is one way to stop it. At every place you fix, stand up one check that says “if this defect returns, I cry”. That is a witness.

★ And the order matters — stand it up before the fix. Put it up afterwards and you cannot know whether it bites. A check that was green from the start and a check that was red because it caught the defect and turned green when it was fixed look identical, and are worth entirely different things.

#!/bin/sh
# Stand the witnesses up *before* the fix.
#
#   (1) Run against the version with the defect - a witness must cry (red).
#       If none cries, that witness guards nothing.
#   (2) Run against the fixed version - all must be quiet (green).
#
# The order is the point. A check seen only green is a check you do not know bites.
set -eu
cd "$(dirname "$0")"
CC=${CC:-cc}
CFLAGS="-std=c23 -Wall -Wextra"

printf '== (1) the version with the defect (a witness must cry)\n'
$CC $CFLAGS -o witness-buggy find-buggy.c witness.c
if ./witness-buggy; then
    printf '   * no witness cried - this witness is useless\n'
    rc=1
else
    printf '   -> it cried, as intended\n'
    rc=0
fi

printf '\n== (2) the fixed version (all must be quiet)\n'
$CC $CFLAGS -o witness-fixed find.c witness.c
./witness-fixed || rc=1

rm -f witness-buggy witness-fixed
exit $rc

== (1) the version with the defect (a witness must cry)
  ok   finds a value in the middle
  ok   finds the first
  FAIL * finds the last - one cell of edge  (got -1, wanted 4)
  ok   an absent value gives -1
  ok   an empty array gives -1 too
a witness cried
   -> it cried, as intended

== (2) the fixed version (all must be quiet)
  ok   finds a value in the middle
  ok   finds the first
  ok   * finds the last - one cell of edge
  ok   an absent value gives -1
  ok   an empty array gives -1 too
all five witnesses are quiet

The demonstration shows that order as it is. Taking the common slip of writing lo < hi for lo <= hi in a binary search, five witnesses were stood up first.

1. Run against the version with the defect and only “finds the last” cries. The other four stay quiet — meaning the witnesses point out where it went wrong as well.
2. On the fixed version all five are quiet.

And each witness carries a sentence on why it matters.

check("* finds the last - one cell of edge", find(sorted, n, 50),  4);

The sentence, not the count, is the asset. Months later, when this check cries, what a person reads is not “check 3 failed” but “it cannot see one cell of the edge”.

103.4 The negative check — does that check really bite#

Make what the witness order taught into a rule and it reads: when you build a new check, break something once, on purpose. This is called a negative check — it confirms not “does it say absent things are absent” but “does it say present things are present”.

The method is simple. Put in on purpose the defect the check is meant to catch, see whether the check cries, and put it back.

103.5 The ratchet — a number that must not grow#

Every project has numbers that “would be nice at zero but cannot be zero today”: the count of warnings, of defects not yet fixed, of places no test reaches. There are two ways to treat such a number — look away, or stop it growing.

The latter is a ratchet. Write today’s number into a file, and if it grows beyond that the gate cries. The name comes from the cogwheel that turns one way only.

★ The last row is what a ratchet is really worth. It does not forbid growth; it makes growth visible. If it is truly needed, raise the baseline. Only, at that moment the change lands in the commit, and review gets to ask “why did this grow?”.

And the tightening is done by a person. If the machine lowered the baseline automatically whenever the number fell, then a number that dipped by chance and rose again could not be stopped — the ratchet would be gone.

103.6 Tiers — you cannot always run everything#

The more checks you stand up, the longer running them all takes. And then people start not running them (the same story as make clean in chapter 102). So checking is given depth as well. Deciding how far to run according to what changed is the tier.

Two disciplines come with it.

1. What changed decides the depth. Edit only documents and there is no reason to run deep; touch a core data structure and you may not slip by shallow.
2. ★ It can only be raised. “We are in a hurry, shallow this once” is the first step in the collapse of the discipline. Depth is not a thing you lower to get a pass.

103.7 One piece of work — separating decision from execution#

Now the procedure. From a request arriving to a commit closing it, the steps a large project actually walks are broadly these.

★ The first step is the one most often skipped and the most expensive. A decision and an execution are different kinds of work.

• Decision — which road to take; whether a public promise changes; whether something others depended on breaks. → Do not settle it alone. Ask.
• Execution — how to carry that decision out. → Do it without asking.

Mix the two and both get worse. Ask about the execution as well and nothing moves; settle the decision alone as well and the whole thing gets undone later.

The second step earns as much. Work that begins with “it seems slow” or “the problem is probably here” often grabs the wrong leg. Plans overturned after measuring are common, and that is normal. When one is overturned, put that in the record — so the next person does not grab the same leg again.

103.8 No silent failures — and the commit is the record of a decision#

Last, one discipline runs through this whole chapter. Do not fail silently.

If you truncated, say you truncated. If you could not measure, say you could not. If you skipped a check, say you skipped it. Because silence is always read as “it was checked and it was fine”.

★ The last row is the dangerous one. “It is zero” and “the check answered zero” are different sentences. A check’s scope is its promise, so what it does not look at must be written down as well.

Then the commit message. Code says what was done but cannot say why (the same story as the design record in chapter 102). So a commit carries these.

1. What was fixed and why — and what was undone, if anything was
2. Which numbers moved, and how (if there is a ratchet)
3. One line on what was learned — so the next person does not grab the same leg

That is the frame of work built by several people over a long time. The next chapter holds all of it against one field — embedded work, where C is most deeply rooted, and what compilers and tools one works with there.