lo/benchmark/CLAUDE.md

Benchmark Guidelines

File Organization

Benchmark files follow the naming convention:

benchmark/{package}_{category}_bench_test.go

• package: core, it, mutable, parallel
• category: slice, map, find, intersect, math, string, type_manipulation, condition, tuples

Shared data generators live in helpers_test.go (and it_helpers_test.go for go1.23 iter helpers).

Performance PRs

Every performance improvement PR must include a benchstat comparison in the PR description. Without before/after numbers, the PR will not be merged.

How to produce a benchstat report

1. Check out master and run the "before" benchmarks:

   git stash && git switch master
   go test ./benchmark/... -bench=BenchmarkXxx -benchmem -count=6 -cpu=1 | tee /tmp/before.txt
   

2. Switch to your branch and run the "after" benchmarks:

   git switch my-branch && git stash pop
   go test ./benchmark/... -bench=BenchmarkXxx -benchmem -count=6 -cpu=1 | tee /tmp/after.txt
   

3. Compare with benchstat:

   benchstat /tmp/before.txt /tmp/after.txt
   

4. Paste the full benchstat output in the PR description.

What to include in the PR description

• The optimization technique (pre-allocation, direct indexing, value receivers, etc.)
• The benchstat table showing time/op, allocs/op, and bytes/op deltas
• An explanation of why the change is faster, not just what changed

When NOT to submit a performance PR

• If benchstat shows no statistically significant improvement (p >= 0.05)
• If the improvement is < 5% and adds code complexity
• If the change regresses other benchmarks — always run the full suite, not just the targeted benchmark

Adding New Benchmarks

When adding a new helper function to the library, add a corresponding benchmark in the appropriate {package}_{category}_bench_test.go file. Use the standard parametric pattern:

func BenchmarkMyFunc(b *testing.B) {
    for _, n := range lengths {
        data := genSliceInt(n)
        b.Run(fmt.Sprintf("ints_%d", n), func(b *testing.B) {
            for i := 0; i < b.N; i++ {
                _ = lo.MyFunc(data, ...)
            }
        })
    }
}

Use shared generators from helpers_test.go — do not create local generator functions.