ArticlesInitiatives

What we mean by done

Verifying the code says the right thing is not verifying that the system does it. The standard we hold ourselves to, and the evidence we expect to see in a review.

A feature is not finished because the code states that it should work. It is finished when someone has observed it working.

Written down, that sounds self-evident. It is not how most software is delivered, and the distance between the two is where most defects reach users.

Two kinds of verification

There is a difference between verifying a configuration and verifying a behaviour.

Verifying the configuration means reading the code and confirming that it says the right thing. The route is declared. The handler is connected. The rule references the correct token. The environment variable is set.

Verifying the behaviour means querying the running system and examining the result. Call the endpoint. Follow the link. Measure the value the browser actually computed. Load the page on the device the reader will use.

The first is quick and resembles diligence. The second is slower, and it is the only one that establishes anything.

Why the distinction matters

Consider a set of styling rules that reference a design token by name, correctly, in twenty-three places, in a build that never emits that token. Every rule resolves to nothing. Components that should be rounded render square.

Reading the code returns the right answer: the rules name the right token. Reading the computed style in the browser takes seconds and returns the actual one. A team that only reads code can be told twice that the component looks wrong and still not locate the cause, because the code is not where the fault is.

Consider a confirmation email pointing at a URL that was correct before a set of pages moved. The template is sound. The constant it uses is sound. The route it names no longer exists. Opening the link once surfaces the error immediately. Reading the template shows a plausible link.

Neither is a difficult problem. Both are invisible to configuration checking alone.

What we require

Our standard is that a claim about behaviour carries evidence from the running system, and that the evidence appears in the pull request.

For an endpoint, that means the request and the response, including the failure cases. Not “the endpoint returns the count”, but the two calls demonstrating that a second request from the same reader does not increment it twice.

For anything visual, the rendered result at the viewport sizes readers actually use, in the longer language and in both themes.

For anything that sends email, the delivered message, read as the recipient will read it, with the links followed.

For a deployment, a request against production after release. A green build demonstrates that the code compiled. It demonstrates nothing about whether the result is reachable.

The economics

The objection is always time. In practice the discipline costs minutes and saves days, for a reason unrelated to diligence: a defect found by its author is a small defect.

Found later, the same defect arrives with overhead attached. Someone has to reproduce it from an imprecise report. The author has lost the context. It may already have shipped, in which case it is present in a cache, a search index, a sent email, or a client’s expectations.

Querying the running system also surfaces what you were not looking for. You confirm that a count is correct and notice that the response takes two seconds. You read one email and find that the unsubscribe link is missing.

What this commits us to

No practice makes a team infallible, and claiming otherwise would be an unverified assertion of precisely the kind this is meant to prevent. What the discipline does is move discovery earlier, where it is inexpensive, and keep “it should work” from being recorded as “it works”.

If a client holds us to one standard, we would choose this one. When we report that something is done, we have seen it done.

The LeySoft newsletter

Stay in the know.

Our latest stories and ideas, delivered to your inbox.

By subscribing, you agree to our Privacy Policy.
Just the good stuff. Unsubscribe anytime.