When should a Go Example use // Unordered output: instead of // Output:?

## The problem it solves An example is checked against fixed text, and fixed text implies a fixed order. That works for almost everything an example prints — except iteration over a map, whose order Go randomises on purpose so that no program can come to depend on it. An example that ranges over a two-key map and prints one line per key will pass and fail alternately with an ordinary `// Output:` block. `// Unordered output:` exists for exactly that shape: ```go func ExampleQuery_Keys() { q := Query{"b": {"2"}, "a": {"1"}} for k := range q { fmt.Println(k) } // Unordered output: // a // b } ``` ## What the comparison actually does It is a sorted line comparison, not a subset test. The runner takes the captured stdout and the expected block, splits both into lines, sorts each set of lines, and compares the sorted sequences. The consequences are worth stating precisely: - Order is irrelevant. - Line **count** still matters. An extra printed line fails. - **Duplicates** still matter. Two identical printed lines require two identical expected lines. - Each line's own content must still match exactly. If a line's text varies between runs, unordered comparison does not save you. So it relaxes exactly one dimension — the order lines appear in — and keeps everything else as strict as `// Output:` is. ## When it is the wrong tool It is tempting to reach for it whenever an example is flaky, and that is usually a misdiagnosis. If the flakiness comes from a value that differs per run — a duration, a generated identifier, a memory address — the printed lines themselves are not stable and no sorted comparison will help. The fix there is to stop printing the unstable value, or to print something derived from it that is stable, such as a boolean or a length. It is also the wrong tool when the output is only *incidentally* unordered. If you are printing map keys, you can sort them into a slice and print in a defined order, then use a plain `// Output:` block. That version is usually the better example for the same reason it is a slightly worse test: the reader sees one predictable result, and the documentation reads like something they could reproduce line for line. The unordered form quietly tells a reader "the order you see here is not real", which is honest but less useful when the order genuinely does not matter to them. A reasonable rule: if the ordering is a detail of the data structure you happen to be iterating, sort it and use `// Output:`. If the ordering is genuinely part of what you are demonstrating being unspecified — the whole point of the example is that these values arrive in no particular order — use `// Unordered output:`. ## Mechanics shared with the ordinary form Everything else about the output block is unchanged. The comment must still be the last comment in the function body, or the example is skipped and never checked. Only `os.Stdout` is captured. Surrounding whitespace is trimmed. The single-line form is not useful here — an unordered block with one line is just an ordinary block — so it is always written as a multi-line block. ## A note on line-shaped output Because the comparison is line-based, an example whose unordered content is not naturally one item per line will not benefit. If you print a whole map with `fmt.Println(m)` you get a single line whose *interior* ordering the map printing does define — Go's map formatting prints keys in sorted order — so that case does not need the unordered form at all. The unordered form is for output you produced yourself, one line at a time, in whatever order the iteration handed the items to you.