How To Hide A Leaky Abstraction In Plain Sight 🔊

Thoughts on how to ease the negative impact of an abstraction leak

Fagner Brack
Jun 30, 2016 · 4 min read
Memorial of USS Arizona in Pearl Harbor, built on top of one of its wrecked ships with an oil leakage that is coming from the bottom of the sea since 1940
Listen to the audio version!

The Law of Leaky Abstractions states that:

All non-trivial abstractions, to some degree, are leaky.

When we try to consume an abstraction to hide complexity:

  • If the abstraction is built on top of a dependency that makes impossible to achieve certain features.
  • Or if the abstraction is built on top of a dependency and that dependency has less power but implements part of a fundamental capability that the abstraction doesn’t have.

… then something is gonna leak.

An efficient abstraction is the one that doesn't let any characteristics of its internals influence in the result presented to the user. It should be totally hidden. Failing to do that is a violation the Principle of Least Astonishment due to the fact it's exposing unexpected side-effects to the users.

However, there is a way to prevent an abstraction from exposing unexpected side-effects to the users:

Make them expected!

If the abstraction is aware of the leaks, it can make the dependency as part of the contract without mentioning its underlying implementation. It can use the abstraction as if the leaked component was naturally a part of it, as long as the user can't perceive the difference.

Wikipedia has a detailed definition of what a leaky abstraction is:

In software development, a leaky abstraction is an abstraction that exposes to its users details and limitations of its underlying implementation that should ideally be hidden away.

The key to this definition here is the part "that exposes to its users details and limitations of its underlying implementation that should ideally be hidden away". It will not be leaky if the abstraction "exposes to its users details and limitations of itself".

An abstraction leak happens when it exposes details and limitations of its underlying implementation to the user, not when it can, instead, successfully expose details and limitations of itself.

For example, let's say there is a library that contains the function random(). It's documented as "a function that generates a random number". The consumer realizes later, after a costly debugging process, that the number is not random under certain circumstances because of the algorithm being used internally to generate randomness. The abstraction allowed the algorithm to be leaked to the user.

Let's say that another similar library also contains the function random(). It's implemented the same way and has the same leaky behavior. But it documents the contract as "a function that generates a random number under circumstances x and y". The user understands it might not be random if the circumstances don't match and they consume the function aware of how it works. The underlying algorithm was not unexpectedly leaked to the user, it became encapsulated in the abstraction itself.

Just because the contract has the behavior of the leaked abstraction, it doesn’t mean that something inside the abstraction was in fact leaked by the eyes of the user. The dependency with a weak capability might be the only way to implement the solution, but what the user perceives is just a behavior that cannot be changed, even though it can seem counterintuitive.

The leaky abstraction was hidden in plain sight.

Exposing an abstraction leak might be the most effective solution to hide it

Besides, this practice can encourage both parties (the A.P.I. author and the A.P.I. consumer) to focus on the communication between the problem and the solution. This works very well with how some Open Source projects document their API.

If an abstraction can successfully hide its leaked source to the user, then for all practical purposes the leak doesn't exist.

Documenting the contract won't prevent the abstraction from leaking to the author, but at least it will prevent from unexpectedly leaking to the user.


Thanks for reading. If you have some feedback, reach out to me on Twitter, Facebook or Github.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store