Imported from oioio-space/unpixel (.claude/skills/go-benchmark/SKILL.md). Install upstream with npx skills add oioio-space/unpixel --skill go-benchmark. Copyright stays with the author.

Go Benchmarking & Performance

Goal: only optimize what's measured. Write a correct benchmark, measure, optimize, and prove the improvement with benchstat before/after.

When to benchmark (the right targets)

Benchmark a function when: it's on a hot path (called in tight loops — e.g. the candidate-search and image-distance core of the port), it allocates heavily, or someone claims it's "slow". Do NOT micro-optimize cold code — clarity wins there (see go-style-guide).

Writing a correct benchmark (Go 1.24+)

func BenchmarkDistance(b *testing.B) {
    img := loadFixture()      // setup OUTSIDE the loop
    b.ReportAllocs()          // always report allocs
    b.ResetTimer()            // if setup was non-trivial
    for b.Loop() {            // Go 1.24+: not `for i := 0; i < b.N; i++`
        sink = distance(img)  // assign to a package-level sink…
    }
}

var sink int // …to stop the compiler eliminating the call

• b.Loop() (Go 1.24+) — keeps setup/cleanup out of the timed region automatically.
• b.ReportAllocs() — allocs/op is usually the real lever.
• Prevent dead-code elimination: store results in a package-level sink.
• Table-driven sub-benchmarks with b.Run(name, …) for input sizes.
• b.RunParallel for contention; b.SetBytes(n) for throughput (MB/s).

Measure

mise run bench                 # go test -bench -benchmem ./...
go test -bench=Distance -benchmem -cpuprofile cpu.prof -memprofile mem.prof ./internal/...
go tool pprof -top cpu.prof    # find the hot frames / allocations

Optimize (typical levers, cheapest first)

1. Reduce allocations: preallocate slices/maps with known size, reuse buffers (sync.Pool, bytes.Buffer), avoid []byte↔string copies (strings.Builder).
2. Avoid reflection / interface boxing on hot paths; use generics or concrete types.
3. Hoist work out of loops; precompute; use slices/maps helpers.
4. Algorithmic improvement (better complexity) beats micro-tuning — escalate to algo-architect if the win is algorithmic.

Prove the gain (mandatory)

mise run bench:baseline        # save baseline BEFORE changing code
# …optimize…
mise run bench:compare         # benchstat baseline vs new → shows %delta + significance

Keep a change only if benchstat shows a statistically significant improvement (and no regression in allocs or other benchmarks). Commit the benchmark alongside the optimization.

Notes

• Benchmark artifacts (bench*.txt, *.prof) are gitignored and cleaned by repo-janitor.
• Don't sacrifice clarity for a tiny gain — measure first, and only optimize where it matters.