Examples as Executable Documentation
Example functions with Output comments in godoc.
//
Search across all documentation pages
Example functions with Output comments in godoc.
Go examples are test functions that pkg.go.dev renders as documentation.
When you add an // Output: comment, go test compares stdout and fails if the example drifts.
They complement table-driven tests by showing the public API the way callers use it.
Quick-reference recipe card - copy-paste ready.
func ExampleAdd() {
fmt.Println(Add(2, 3))
// Output: 5
}When to reach for this:
ExampleUser_Marshal)package greet
import "fmt"
func Hello(name string) string {
if name == "" {
return "Hello, world"
}
return "Hello, " + name
}
func ExampleHello() {
fmt.Println(Hello("Ada"))
// Output: Hello, Ada
}
func ExampleHello_empty() {
fmt.Println(Hello(""))
// Output: Hello, world
}What this demonstrates:
ExampleHello documents the common path_empty adds a second documented scenariogo test verifies printed output matches the comment_test.go with production code in the same moduleExample or ExampleXxx are collected by go test._ disambiguates multiple examples (ExampleSort_reverse).ExampleDoc (no suffix) can document a whole package when paired with package greet in the file.// Output: compares trimmed stdout; use // Output:\n for multiline expected text.| Name pattern | Appears on |
|---|---|
ExampleFoo | Function Foo |
ExampleBar_qux | Function Bar (scenario qux) |
ExampleMyType | Type MyType |
ExampleMyType_method | Method on MyType |
func ExampleShuffle() {
// shuffle output - compile only, no Output comment
rand.Shuffle(3, func(i, j int) { /* ... */ })
}Omit // Output: when output is nondeterministic; the example still must compile.
go test after every doc change; update the comment when behavior changes.package foo or foo_test.Output is exact string match. Fix: Match spacing; prefer fmt.Printf with explicit format when teaching APIs.package foo_test examples cannot show unexported helpers. Fix: Use package foo for internal mechanics only when exported API allows.| Alternative | Use When | Don't Use When |
|---|---|---|
| README code blocks | Narrative tutorials | You need CI verification |
| Table-driven tests | Exhaustive cases | Teaching one happy path |
go doc comments only | Trivial one-liners | Output shape matters |
| Playground on pkg.go.dev | Shareable snippets | Repo must build without network |
Yes - go test executes them with other tests in the package.
Failed Output checks fail the build.
No - examples must be void functions.
Use fmt.Print to demonstrate results.
Print each value or a formatted struct with fmt.Printf("%#v", v).
Rare - documents package initialization.
Most packages use ExampleFunc instead.
Avoid it - examples should use stdlib only so godoc stays dependency-free for readers.
Use httptest and print the recorder body - keep it short.
Long flows belong in normal tests.
No - exact match only.
For unordered map output, print sorted keys or skip Output.
example_test.go or foo_test.go beside production code.
go test picks them up automatically.
They run locally but internal paths do not appear on public pkg.go.dev the same way.
Prefer examples on exported module APIs.
Run the example with go test -run ExampleHello -v, copy actual stdout into the comment.
No - benchmarks use BenchmarkXxx(*testing.B).
Examples measure documentation, not performance.
Unexported example names are not shown.
There is no //go:example off - delete or rename if not ready.
Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).
Reviewed by Chris St. John·Last updated Jul 16, 2026