The jargon glossary
Technical conversation runs on a dense layer of metaphors and terms of art that nobody defines out loud, because everyone is assumed to know them: a design has "sharp edges", the API is a "footgun", latency lives "in the p99 tail", the fix is a "backport", and please do not "poke the bear" before the audit. This chapter is the decoder: the jargon grouped by domain, each entry with a plain meaning and a real sentence showing how it is used. Some terms got fuller treatment in the senior lexicon and the describing chapter; those are cross-noted rather than repeated in depth. This is a lookup chapter; skim it once, return to it often.
Metaphor idioms: the culture layer
The figures of speech that carry engineering judgment. Most are about risk and effort.
| Term | Meaning | Example |
|---|---|---|
| poke the bear | Provoke something risky that is currently quiet | "Let's not poke the bear by touching auth the week before the audit." |
| footgun | A feature or API that makes it easy to hurt yourself | "The config lets you set a negative timeout; that's a footgun and we should validate it." |
| sharp edges | Parts that are dangerous or easy to misuse | "The client works, but it has sharp edges around retries; document them loudly." |
| rough edges | Parts that are unpolished but not dangerous | "Ship it; the UI has rough edges we can smooth next sprint." |
| happy path | The no-errors, everything-works execution route | "The demo shows the happy path; the interesting bugs are all off it." |
| rabbit hole | A deep, absorbing tangent far from the goal | "I went down a rabbit hole on the allocator; fascinating, irrelevant." |
| yak shaving | Nested prerequisite work far from the actual task | "Fixing the test needed a new fixture, which needed a Docker bump; pure yak shaving." (see Ch 14) |
| bikeshedding | Arguing over trivia because it is easy | "We spent the review bikeshedding the log format; the schema got two minutes." (see Ch 14) |
| boil the ocean | Attempt everything at once | "Let's not boil the ocean; migrate one tenant, learn, then scale." |
| low-hanging fruit | The easy, cheap wins | "Before the rewrite, let's grab the low-hanging fruit: the two N+1 queries." |
| gold plating | Over-polishing beyond what the problem needs | "Retry jitter is gold plating for an internal tool nobody pages on." |
| bus factor | How many people must vanish before knowledge is lost | "The vault has a bus factor of one, and that one is Yuki; we need to spread it." |
| dogfooding | Using your own product internally before customers do | "We're dogfooding the new checkout on the company store this week." |
| rubber duck | Explaining a problem aloud to find the answer yourself | "Rubber-duck me for a sec; I think I'll spot it by describing it." |
| greenfield / brownfield | A fresh build with no constraints / building amid existing systems | "Greenfield would be Postgres, but this is brownfield and everything already speaks Dynamo." |
| snowflake | A one-off, hand-tuned, non-reproducible thing | "That server is a snowflake; nobody dares reboot it because nobody can rebuild it." |
| paper cut | A small individually-trivial annoyance that accumulates | "None of these bugs is a P1, but the paper cuts are killing the onboarding flow." |
| lift and shift | Move a system as-is without redesigning it | "Phase one is a lift-and-shift to the new account; the refactor is phase two." |
| spike | A timeboxed investigation whose output is knowledge, not code | "Two-day spike to find out if the vendor API can even do this, then we estimate." |
| long tail | The many rare cases that collectively matter | "Ninety percent of queries are five products; the long tail is the other 40,000." |
| north star metric | The single metric that best captures product value | "Our north star is weekly repeat purchases, not signups." (see Ch 14) |
| war room | A focused all-hands space (physical or virtual) during a crisis | "Spinning up a war room for the outage; incident channel is #inc-214." |
| toil | Manual, repetitive operational work that should be automated | "On-call is 80% toil right now; three scripts would halve the pages." |
Don't be confused: footgun, sharp edges, and rough edges shade into each other but are not equal. A footgun is actively dangerous by design: the easy path leads to harm (an API that deletes without confirmation). Sharp edges are hazardous spots you can cut yourself on if careless, but the normal path is safe (a retry helper that double-charges only if you misconfigure it). Rough edges are merely unpolished and harmless (a clunky error message, a missing keyboard shortcut). Calling a rough edge a footgun cries wolf; calling a footgun a rough edge ships an incident. Match the word to the blast radius.
Performance and scale
The vocabulary of "how fast" and "how much". Percentiles are the heart of it (see also Ch 12).
| Term | Meaning | Example |
|---|---|---|
| p50 / p95 / p99 / p999 | The Nth-percentile value (usually latency): pN means N% of requests are at or below it | "p50 is fine at 40ms; p99 is 1.2s, so one in a hundred users waits over a second." |
| tail latency | The slow high-percentile end (p99 and beyond) | "The average hides it; all our pain is in the tail." |
| hot path | The code that runs most often; small costs there multiply | "Don't allocate on the hot path; this runs per request." (see Ch 14) |
| cold path | Rarely-run code where clarity beats speed | "The migration is a cold path; readability over cleverness." |
| big O / O(n) | Asymptotic growth of cost as input grows | "This is O(n squared) in tenants; fine at 10, a fire at 10,000." |
| amortized | Average cost per operation across a long run, even if some ops are expensive | "Appending is amortized O(1): most appends are instant, the occasional resize is O(n)." |
| cardinality | The number of distinct values | "user_id is high-cardinality; don't make it a metric label or the dashboard explodes." |
| throughput / QPS / rps | Volume handled per unit time (queries/requests per second) | "We're CPU-bound at about 900 rps; IO still has headroom." |
| headroom | Slack remaining before a limit | "Two-x headroom on CPU, but IOPS is the bottleneck." (see Ch 14) |
| backpressure | A system pushing back on producers instead of drowning | "There's no backpressure between ingest and the workers; that's the outage." (see Ch 14) |
| thundering herd | Many clients retrying or waking at once and overwhelming a resource | "Cache expiry with no jitter gave us a thundering herd at the top of every hour." |
| hotspot / hot key | One shard or key taking disproportionate load | "Tenant 7 is a hot key; it alone is half the queue traffic." |
Don't be confused: mean, median, and p50 are not interchangeable, and confusing them misreads performance. The median is the middle value, which is exactly p50. The mean is the arithmetic average, and for latency it lies: one 30-second request among a thousand fast ones barely moves the median but wrecks the mean. "Average latency is 60ms" can hide a p99 of two seconds. This is why teams report percentiles, not averages: users experience the tail, and the mean is the one number that pretends the tail is not there. When someone quotes you an "average" latency, ask for p95 and p99.
Distributed systems and data
The terms for systems that span machines and outlive a single request. This is where the deepest jargon lives.
| Term | Meaning | Example |
|---|---|---|
| idempotency | Applying an operation twice has the same effect as once | "Make the handler idempotent with a request key; then retries stop double-charging." (see Ch 14) |
| tombstone | A marker that a record was deleted, kept so the deletion propagates before physical removal | "The row still shows in the raw store as a tombstone; compaction reaps it later." |
| watermark | A marker of event-time progress in a stream ("we've seen everything up to time T") | "Late events past the watermark get dropped from the window; that's why the 23:59 order missed the batch." |
| phantom read | A transaction re-runs a range query and sees new rows a concurrent commit inserted | "Two concurrent 'count open carts' reads disagreed: a phantom read, we need a higher isolation level." |
| dirty read | Reading data another transaction wrote but has not committed | "At this isolation level you can dirty-read a balance that gets rolled back a millisecond later." |
| eventual consistency | Replicas converge over time, not instantly | "The read replica is eventually consistent; a just-written card can be missing for a beat." |
| replication lag | How far a replica trails the primary | "Replication lag spiked to 8s; that's why saved cards vanished right after saving." |
| quorum | The minimum number of nodes that must agree for an operation to count | "Writes need a quorum of 2 of 3; one node down is fine, two is read-only." |
| split brain | A partition where both sides think they are the leader | "The network partition gave us split brain; both regions accepted writes and now they conflict." |
| at-least-once / at-most-once / exactly-once | Delivery guarantees: never lost but maybe duplicated / never duplicated but maybe lost / neither | "The queue is at-least-once, so the consumer MUST be idempotent or we double-file." |
| CAP | Under a network partition you choose consistency or availability, not both | "We chose AP for the cart: available and eventually consistent beats correct-but-down." |
| blast radius | How much is affected when something fails | "Per-tenant queues shrink the blast radius; one bad message no longer stalls everyone." (see Ch 14) |
Statistics and experimentation
The numbers-and-evidence vocabulary, which engineers meet most at A/B-test and metrics time. Precision here prevents expensive wrong conclusions.
| Term | Meaning | Example |
|---|---|---|
| A/B test | A randomized experiment comparing variant A against variant B | "The A/B test gave the new layout +3% checkout; ran two weeks, split 50/50." |
| mean / median / mode | Average / middle value / most frequent value | "Median session is 4 minutes; the mean is 11 because a few users never log off." |
| statistical significance | The result is unlikely to be noise | "The lift isn't significant yet; the confidence interval still crosses zero." |
| p-value | The probability of data at least this extreme if the null hypothesis (no effect) were true | "p = 0.03, so under 'no real effect' this result would be rare; we reject the null." |
| confidence interval | The plausible range for the true value | "The effect is +3% with a 95% CI of +1% to +5%; real, and we know the size roughly." |
| sample size / power | How much data you have / the ability to detect a real effect | "Underpowered: 200 users can't detect a 1% change, so 'no effect' means 'we couldn't tell'." |
| effect size | How big the difference is, apart from whether it is real | "Significant but tiny: a 0.1% effect that's statistically real and practically pointless." |
| false positive / false negative | Alarm with no fire / fire with no alarm | "The fraud model's false positives block real customers; false negatives let fraud through. Pick your threshold with both in view." |
| base rate | The background frequency of a thing | "A 99%-accurate test for a 1-in-10,000 event is mostly false positives; base rates matter." |
Don't be confused: the p-value is the most misquoted number in engineering. It is not the probability that your hypothesis is true, and it is not the probability the result is a fluke. It is: assuming there is no real effect, how surprising is data this extreme? A small p-value (say under 0.05) means "this would be unlikely if nothing were going on", which is evidence against 'nothing going on', not proof of your specific story. Two traps follow: a significant result can have a trivial effect size (real but too small to care about), and a non-significant result is not proof of no effect (you may just lack the sample size). Report the effect size and the interval, not the p-value alone.
Release, change, and version management
The vocabulary of shipping and un-shipping.
| Term | Meaning | Example |
|---|---|---|
| rollback | Revert to the previous known-good version | "Rollback of the 14:00 deploy stopped the bleeding in eleven minutes." |
| roll-forward / rollforward | Fix by deploying a new version forward, rather than reverting | "The schema already migrated, so we can't roll back cleanly; we roll forward with a patch." |
| backport | Apply a change made on a newer version onto an older, still-supported one | "The security fix landed in v5; backport it to v4 for the customers who haven't upgraded." |
| forward-port | Apply a change made on an old branch onto the newer mainline | "Your hotfix on the release branch needs a forward-port to main or it'll regress next release." |
| cherry-pick | Apply one specific commit onto another branch | "Cherry-pick just the logging commit into the hotfix; leave the refactor behind." |
| feature flag | A runtime toggle to enable/disable code without deploying | "It's behind the retry_cap flag, default off; we enable per region." |
| canary | A small early slice of traffic that detects trouble first | "Canary at 1% caught the memory climb before the full rollout." |
| blue-green | Two identical environments; switch traffic between them for zero-downtime release | "Blue-green cutover: bring green up, flip the router, keep blue warm for rollback." |
| dark launch | Ship code that runs but is invisible to users, to test at load | "Dark-launched the new ranker: it scores every request, we just don't show it yet." |
| ramp | Gradually increase a rollout percentage | "Ramp to 10, watch an hour, then 50; hold overnight before 100." |
| deprecate / sunset | Mark as discouraged-but-working / remove entirely | "Deprecated in Q3, sunset in Q1; the timeline is in the ADR." (see Ch 14) |
Don't be confused: backport and forward-port move changes in opposite directions and are constantly swapped by mistake. Think of version numbers as a timeline: backport carries a fix back in time to an older version still in the field (new to old); forward-port carries a change forward onto newer code (old to new). You backport a security patch so last year's release gets it too; you forward-port a release-branch hotfix so next release does not silently lose it. And rollback versus roll-forward is a third axis entirely: rollback returns to the old version, roll-forward ships a new one to fix the problem. When migrations have already run, rollback is often impossible and roll-forward is the only door.
Design and code principles
The named ideas behind "clean" code. Most are acronyms.
| Term | Meaning | Example |
|---|---|---|
| SOLID | Five OO design principles (expanded below) | "This class violates the S in SOLID; it parses, validates, and persists." |
| DRY | Don't Repeat Yourself: one source of truth for each fact | "The timeout is defined in three files; DRY it into config." |
| YAGNI | You Aren't Gonna Need It: don't build for imagined futures | "YAGNI on the plugin system; we have one plugin and no second in sight." |
| KISS | Keep It Simple: prefer the plain solution | "KISS: a cron job beats the event-driven pipeline for a daily report." |
| separation of concerns | Each module owns one kind of responsibility | "Separate transport from business logic; right now the handler does both." |
| coupling / cohesion | How dependent modules are on each other / how focused a module is internally | "Low cohesion and high coupling: the worst quadrant, and exactly this module." |
| single source of truth | One authoritative place for a given fact | "The wiki and the code disagree on the limit; make the code the single source of truth." |
| pure function / side effect | Output depends only on input, no external change / any external change (I/O, mutation) | "Keep the scorer pure; push the side effects (the DB write) to the edge." |
| leaky abstraction | A wrapper that forces callers to know what it hides | "The ORM is a leaky abstraction here; you can't use it without knowing the SQL it emits." (see Ch 12) |
SOLID, expanded, since it is five ideas in one word:
- S, Single responsibility: a class should have one reason to change. "Split the class: one reason to change is the tax rules, another is the storage format."
- O, Open-closed: open to extension, closed to modification. "Add a new payment type by adding a class, not by editing the switch statement."
- L, Liskov substitution: a subtype must work anywhere its base type does. "This SavingsAccount throws on withdraw; it breaks Liskov, callers of Account don't expect that."
- I, Interface segregation: many small interfaces beat one fat one. "Clients that only read shouldn't have to implement the write methods."
- D, Dependency inversion: depend on abstractions, not concretions. "The service should depend on a Store interface, not on Postgres directly, so tests can swap it."
Work and process idioms
The meta-vocabulary of how the work itself flows.
| Term | Meaning | Example |
|---|---|---|
| context switch | The cost of jumping between tasks | "Five small pings fragmented my morning; the context switches cost more than the work." |
| WIP (limit) | Work in progress; a cap on how much runs at once | "Our WIP is too high; we have eight things half-done and nothing shipped. Cap it at three." |
| procrastination / yak shaving | Deferring the hard task / burying it under prerequisites | "Reorganizing my tabs is procrastination with extra steps; I'll just start the migration." |
| on-call / paged | Being the responder for incidents / being alerted by the system | "I'm on-call this week; got paged at 3am for a false alarm on queue depth." |
| blameless | A culture that debugs systems, not people | "Blameless postmortem: we ask what made the mistake easy, not who made it." (see Ch 8) |
| land grab | Claiming ownership of an area, often politically | "The reorg turned into a land grab over who owns the queue roadmap." (see Ch 38) |
| drive-by | A quick, low-context contribution or comment | "Drive-by review comment, not blocking: consider a set here." |
Using the glossary
Three closing rules that outlast any single term. Mirror your team: every group uses a subset, and a term that is native in one org ("footgun" everywhere, "tombstone" only where there is an LSM store) is exotic in another; two weeks of reading your channels tells you the local dialect (Chapter 15's harvest-locally rule). Expand on first use with newcomers present: "the p99 (the latency one in a hundred users hits)" costs five words and includes everyone. And never let the jargon carry the load-bearing part of a claim to a non-specialist: a PM does not need "the write path isn't idempotent", they need "if the network hiccups we might double-charge someone", which is the same fact translated (Chapter 21). The glossary is for speaking precisely to people who share it, not for proving you belong.
👉 That is the last of the pure reference material, but not the last of the examples. The next part is a compendium: roughly ninety named situations, from "you joined the meeting late" to "someone takes credit for your work", each one written from both sides with a full spread of sentences. On to Chapter 46.