In a Go package, an Example function prints the wrong text yet go test passes. Why?

## The failure mode: a check that fails open Most test failures announce themselves. This one does the opposite. An example that is not run cannot fail, so a package can carry a set of examples that look like verification, render on the documentation page as if they were authoritative, and check nothing at all. For a library other teams read before they read your code, that is worse than having no examples: the documentation now asserts behaviour that nothing enforces. ## The three ways it happens **1. There is no output block.** The example prints, the runner has nothing to compare against, and the function is skipped. This is the common case and it is easy to create by accident: you write the example first to see what it prints, intend to paste the output in, and never do. **2. The output block is no longer last.** The tooling looks at the *last* comment in the function body. A later edit that adds a trailing note — `// TODO: cover the empty case` under the output block — moves the output block out of that position, and the example goes quiet. Nothing about the diff looks dangerous, which is exactly why this survives review. ```go func ExampleCanonical() { fmt.Println(Canonical("https://example.com/p?b=2&a=1")) // Output: https://example.com/p?a=1&b=2 // TODO: also cover an empty query } ``` **3. The name is not recognised.** The character after `Example` must not be lower-case, so `Examplecanonical` is an ordinary function that nothing calls. A misspelt symbol name — `ExampleCanonicl` after a rename — still runs if it has an output block, but it attaches to no symbol, so it disappears from the documentation page while quietly continuing to pass. ## Diagnosing it The fastest confirmation is the verbose run listing: ``` $ go test -run Example -v ./... === RUN ExampleCanonical --- PASS: ExampleCanonical (0.00s) PASS ``` The listing names every example that actually executed. An example you can see in the source but not in that output was skipped, and you now know which of the three causes to look for. Note that `-run` accepts a regular expression matched against test, example and fuzz-target names, which is why `-run Example` is a convenient filter here. A second, blunter check: temporarily break the example's expected output — change one character in the `// Output:` block — and re-run. If the package still passes, the example is definitively not running. This is worth doing once on any example you are about to rely on. `go vet` covers the name-shaped causes. Its test checks report an example whose name has a lower-case letter after the prefix, one whose signature is not niladic, one with a malformed suffix, and — for an example written against the package's exported surface from its external test package — one whose name refers to an identifier that does not exist. It does not report a missing output block, because an example without one is legitimate: it is still a compile check on the documentation, and for output that cannot be made deterministic it is the only honest choice. ## Keeping it fixed The defect is structural, so the fix is structural rather than a matter of care: - Run `go vet` in the build, not by hand. It is the only automated catch for the naming variants. - When reviewing an example, look at where the output block sits, not just that one exists. "Last comment in the body" is the actual rule and it is invisible unless you are looking for it. - Treat an example with no output block as a deliberate, commented decision — say in the body why the output cannot be checked. An unexplained one is indistinguishable from a forgotten one. - Prefer several small suffixed examples over one that prints many lines. A long output block drifts one line at a time and is re-pasted wholesale when it breaks, which is how a stale expectation gets blessed. - When an example's expected output does change, read the diff of the output block as carefully as a diff of the code. It is the specification. ## Why the design accepts this The alternative — refusing to build an example without an output block — would forbid the legitimate case where a function's result cannot be printed deterministically but the calling code is still worth showing. Go chose to keep the compile-only example useful and accept that the check is opt-in. Once you know the check is opt-in, the review habit follows: assume an example is not verifying anything until you have seen its name in a `-v` run.