Build fluency in the vocabulary of an abstraction that fails to fully hide the details beneath it.
0 / 5 completed
1 / 5
At standup, a dev mentions an abstraction meant to hide how a remote file-storage API works internally, but callers still have to understand its underlying network retries and timeout behavior to use it correctly, because those details leak through the interface. What is this called?
A leaky abstraction is exactly this: it is an abstraction that fails to fully hide its underlying implementation details, such as network retries and timeout behavior in a remote file-storage API, forcing callers to understand what's happening beneath the interface anyway in order to use it correctly. A hash collision is an unrelated hash-table concept about two keys sharing a bucket. This underlying-details-leak-through pattern is exactly why a leaky abstraction fails to deliver the simplicity an abstraction is supposed to provide.
2 / 5
During a design review, the team redesigns a file-storage abstraction to surface an explicit, documented timeout and retry policy as part of its public interface, specifically because forcing callers to guess at hidden network behavior was worse than exposing it deliberately as a designed part of the API. Which capability does this provide?
Deliberately exposing the behavior here provides an honestly designed interface instead of an accidentally leaky one, since deliberately exposing timeout and retry behavior as documented parameters lets callers plan for it explicitly, instead of discovering hidden network behavior only by hitting unexpected failures. Fully hiding all network behavior with no leak and no documented exposure at all is often impossible for a remote API, since network failures are a real characteristic callers eventually have to handle regardless. This expose-it-deliberately-instead-of-accidentally behavior is exactly why acknowledging an abstraction's inevitable leaks and designing for them is preferred over pretending they don't exist.
3 / 5
In a code review, a dev notices a file-storage abstraction's documentation claims callers never need to think about network behavior, yet callers who don't add their own retry logic see silent data loss during transient network blips that the abstraction was supposed to hide. What does this represent?
This is a leaky abstraction, since the underlying network retry and failure behavior leaks through to callers in the form of silent data loss, despite documentation claiming the abstraction fully hides it. A cache eviction policy is an unrelated concept about discarded cache entries. This claims-to-hide-but-actually-leaks pattern is exactly the kind of mismatch a reviewer flags once an abstraction's documentation promises more than its implementation can actually deliver.
4 / 5
An incident report shows silent data loss occurred in production during a transient network blip, because a file-storage abstraction's documentation claimed callers never needed to handle network behavior, so no caller added retry logic for a leak the abstraction never acknowledged. What practice would prevent this?
Documenting the file-storage abstraction's real, leaking network behavior explicitly lets callers add appropriate retry logic instead of trusting a claim that the abstraction fully hides network behavior it actually doesn't. Continuing to document the abstraction as fully hiding network behavior regardless of how often the underlying leak causes silent data loss for callers who trusted that claim is exactly what caused the data loss described in this incident. This document-the-real-leak approach is the standard fix once an abstraction is confirmed to leak behavior its documentation denies.
5 / 5
During a PR review, a teammate asks why the team documents a leaky abstraction's real underlying behavior instead of trying to build a perfectly sealed abstraction that hides the network entirely. What is the reasoning?
Acknowledging and documenting the leak is realistic, since a remote network call can always fail or time out in ways no abstraction can fully hide, while claiming to have built a perfectly sealed abstraction gives callers false confidence and leaves them unprepared for the leak that will eventually surface anyway. This is exactly why documenting a leaky abstraction's real behavior is the standard practice, rather than pretending an abstraction over an inherently unreliable resource like the network can be made perfectly sealed.