{
  "$type": "site.standard.document",
  "canonicalUrl": "https://jacob.blog/notes/law-of-leaky-abstractions",
  "description": "Why every useful abstraction eventually forces you to learn what it hides, and what that means for frameworks and APIs.",
  "path": "/notes/law-of-leaky-abstractions",
  "publishedAt": "2021-06-06T00:00:00.000Z",
  "site": "at://did:plc:ckthoyuvsmkp254fyuinyzb2/site.standard.publication/3mndm6tiamb26",
  "tags": [
    "software-engineering",
    "principles"
  ],
  "textContent": "Abstractions promise that you can work at one level and ignore the layers underneath. The promise is never fully kept.\n\n> All non-trivial abstractions, to some degree, are leaky.\n\nJoel Spolsky named the pattern in The Law of Leaky Abstractions (2002). A leak is any moment where the hidden layer shows through and you have to reason about it to fix the bug or ship the feature.\n\nTCP is the classic teaching example. The abstraction is a reliable byte stream. Under load or on bad Wi-Fi you still see timeouts and retries. You are not wrong to think in streams. You are wrong to think you will never open Wireshark or read ECONNRESET.\n\nDatabases and ORMs leak the same way. SQL is supposed to hide storage layout until you need an index or to debug a lock. ORMs add another layer, where you’ll stay in objects most weeks but once production slows down you have to dive in deeper with EXPLAIN.\n\nFrameworks and hosted platforms compress more surface area (routing, auth, deployment, observability). That compression buys speed until the failure mode lives in configuration, cold starts, IAM, or a dependency version the template never mentioned. The stack trace points through generated code you did not write.\n\nThe uncomfortable implication is pedagogical. You cannot learn only the top layer and stay competent when the leak appears. Spolsky’s ASP.NET example was blunt on purpose: if the web request fails, you still need HTTP, HTML, and the network path the page took. The abstraction did not remove that work. At best it deferred it, but more likely it hid the underlying complexity until that complexity mattered too much.\n\nTreat leaks as normal maintenance rather than a failure of the abstraction. When you adopt a tool, ask what layer will surface first when things go wrong (I/O, concurrency, persistence, auth, money). Keep a shallow working model of that layer _before_ you get paged. The abstraction still earns its keep on the happy path. It just does not let you skip the floor below forever.",
  "title": "Law of leaky abstractions"
}