A Go library's doc comment shows a usage snippet that no longer compiles. How do you stop that drift?

## The failure you are fixing A doc comment is text. Every convention around it — start with the identifier, indent code blocks, link with brackets — is about how it is *rendered*, never about whether it is *true*. Indented lines inside a comment look like Go, are highlighted like Go and are read like Go, but no compiler ever sees them. So the sketch that was correct when it was written survives every rename, every added parameter, every changed return signature, and stays on the package's front page saying something false. The person who discovers it is a stranger, in an issue titled "the example in the docs doesn't work", and by then it has been wrong for months. That asymmetry is the whole argument: the code in a comment is the only code in the repository that nothing checks. ## Example functions Go's answer is that documentation examples are *code*. An example is a function named with the `Example` prefix, living in a `_test.go` file alongside the package: ```go func ExampleTrimSpace() { fmt.Println(strings.TrimSpace("\t hello \n")) // Output: hello } ``` Two separate guarantees come out of this, and it is worth being precise about which one you get from what: 1. **It compiles.** The file is part of the package's test build, so the example is a real caller of the API. Rename the function, add a parameter, change a return type, and the build breaks — locally, and in CI, in the same run as everything else. This guarantee is free and you get it whether or not you assert anything. 2. **Its output is checked.** If the last thing in the function body is a comment of the form `// Output:` followed by the expected text, the example is executed, its standard output is captured, and it is compared against that text after trimming leading and trailing space. A mismatch is a test failure. Now the documented *result* is verified, not just the documented *call*. The corollary matters when you are advising a team: an example with no `// Output:` comment is compiled but not run. That is still the larger half of the value — it catches signature drift, which is what actually breaks users — but it does not catch behaviour drift, so do not describe such an example as verified. ## Write it as a user, not as an insider A `_test.go` file may declare `package foo` or `package foo_test`. For examples, prefer the external form: ```go package console_test ``` Inside it you can only reach the exported surface, so the example is forced to demonstrate what a user can actually do. An example in the internal package can quietly reach for an unexported constructor, and then it documents a path nobody outside can take — and it keeps compiling after you accidentally unexport something, so it stops protecting the thing you wanted protected. The external form also sidesteps import cycles when the example needs a package that imports yours. ## What to do about output you cannot pin Some results are genuinely not stable: a timestamp, an address, anything derived from map iteration, anything concurrent. Do not paper over it by asserting one observed run — that produces a flaky test and teaches people to ignore it. The options, in order of preference: restructure the example to print something derived and deterministic (a count, a sorted slice, a boolean); print a fixed value that the interesting call merely feeds; or drop the `// Output:` comment and accept a compile-only example. Choosing deliberately between those is the judgment part of this question. ## What stays in the doc comment Not nothing. The prose still has to say what the thing does and what the caller must do — and it should point at the example, which documentation tooling renders next to the symbol so the two arrive together. A one- or two-line indented sketch in a comment is still fine where it is illustrative rather than load-bearing; the smaller it is, the less surface it has to rot. What you are removing is the twenty-line "here is how you use this package" block that is the single most likely thing in the repository to be wrong. ## Making it stick The reason this works organisationally is that it needs no new process. Examples run under `go test ./...`, which CI already does, so a rotted example fails the same pipeline as a rotted unit test and is fixed by the person who broke it, in the change that broke it. Compare with a doc-comment snippet, whose maintenance depends on someone remembering to reread prose while changing a signature — which is exactly the discipline that failed and produced the issue you are answering.