performance-discipline

Files (1)

• SKILL.md

SKILL.md (first lines)

# Performance Discipline

Awareness or performance is critical when writing code as it affects design decisions. And the code is the design.

New code without performance checks is not done.

## Measure, do not reason

- Criterion-style micro-benchmarks for hot paths. A hot-path change ships with the benchmark that shows what it did.
- Profile before optimising. A flame graph (perf, cargo-flamegraph) tells you where time actually goes. Optimise what the profile points at, not what you assume.
- Performance is a sensor in the `implementation-loop`: ship the change, run the benchmark, read the number back.
- Performance tests are environment sensitive, baseline first.
- "noise is large" is not an explanation, it is a finding about the instrument. Fix it.

## The per-decision cost choices

The defaults are often wrong for a hot path.

- **Mutex or not.** A lock on a hot path serialises it. Reach for it deliberately. On thread-per-core, prefer a structure that does not need the lock at all.
- **Heap or stack.** Heap allocation on a hot path costs. Default to the stack; reach for the heap when the data outlives the frame or is large.
- **Hot path or cold path.** Know which you are on. Push allocation, logging, and formatting onto the cold path.
- **Batch, amortize, coordinate.** Do not pay a network hop, syscall, or lock per item when you can coordinate and pay it once for many. Often the single biggest win.
- **Secret state machine bloat** Compilers build a complex data structure to manage async/await boundary state machines. The hidden cost of async/await. Sometimes moving to the heap is a win here.

## The bar

- No "this should be fast enough" without a number.
- No optimising a path you have not shown is hot. Cold-path simplicity beats cold-path speed.
- A hot-path change with no benchmark is not finished.
- A perf verdict from a suspect instrument is "re-verify on a clean one", never closed.

From utilitydelta/build-method, MIT.

More from utilitydelta/build-method