performance-hints

name

performance-hints

description

Estimate-first performance engineering from Jeff Dean and Sanjay Ghemawat's Abseil performance hints, applied to Python/Django, TypeScript/Node, and Vue. Use when the user asks to make something faster, optimize a slow endpoint or job, reduce latency or memory, fix an N+1, cut allocations, profile or benchmark code, size a performance budget, or asks why something is slow. Do not use for general code review, testing, or API design requests that lack a performance angle.

Performance Hints

Estimate the cost before you write the code. Measure the result before you call it done.

Philosophy

"In established engineering disciplines a 12% improvement, easily obtained, is never considered marginal." - Donald Knuth

Knuth's line about premature optimization is usually quoted with its ending cut off. The full passage continues: "Yet we should not pass up our opportunities in that critical 3%." Choose the faster alternative during development when it does not cost readability. This matters most in library code, where your performance problem becomes every caller's performance problem.

Why "optimize later" fails

1. Flat profile. Cost distributed everywhere leaves no hotspot to find later.
2. Callers suffer. Downstream users cannot fix your slow code.
3. Wide use freezes design. Once a system is in production, the changes that would fix it are the ones nobody will risk.
4. Expensive workarounds. Teams buy hardware instead of fixing a solvable problem.

The order that works

1. Estimate. Count operations, multiply by known costs, find the dominant term.
2. Measure. Confirm the estimate against reality before changing anything.
3. Diagnose. A profile shows where time goes, not what to fix. Find the real cause.
4. Fix the dominant term. Everything else is noise until it is the largest term.
5. Measure again. Compare against the baseline you captured.