Applying Single Level of Abstraction


I am reading Designing Elixir Systems with OTP where they introduce the concept of Single Level of Abstraction.


This concept looks rather bizarre and abstract but with an example it becomes easier to understand. Using the examples in the book, imagine we have a starting code like the following:

def select_question(quiz), do: 
  |> Map.put( :current_question, select_a_random_question(quiz) ) 
  |> move_template(:used)
  |> reset_template_cycle

This code is not horribly hard to read, but we are dealing with 2 levels of abstraction here:

  1. The Map.put deals with Elixir basic data types (map)
  2. The rest of the code affects an abstraction called question.

So based on this principle, the authors proposed a new version of the code:

def select_question(quiz), do:
    |> pick_current_question()
    |> move_template(:used)
    |> reset_template_cycle()

defp pick_current_question(quiz), do:
  Map.put(quiz, :current_question, select_a_random_question(quiz))

My issues

This principle looks nice, but I have a couple of issues with it:

  1. It adds a level of indirection
  2. When is enough enough? When do you know when to use it?

To better explain, I will give another example from the book:

  def new(%Template{} = template), do:
    |> evaluate(template)

This piece of code also deals with 2 abstractions:

  1. Enumerable data types from elixir
  2. The concept of a template

So, according to this rule, the code could be improved:

  def new(%Template{} = template), do:
    |> generate_substitutions()
    |> evaluate(template)

  defp generate_substitutions(%{substitution: _sub} = generator), do:

However the authors choose not to do it.


I wonder if they decided the level of indirection was not worth it. If so, how and when do you decide the indirection is worth it or not? What criteria do you usually use?


As it happens, i am currently also reading Designing Elixir Systems with OTP and was wondering about this abstraction too.

Thanks for bringing it up! I hope someone is able to enlighten us :slight_smile:

I don’t see this as having anything to do with introducing abstractions but with capturing and communicating intent.

Three months after writing the code:

Scenario 1:

Map.put( :current_question, select_a_random_question(quiz) ) 

I have to mentally parse this Elixir code in order to discover what it is doing and then divine from the context in which the code exist why it is doing it - and the why is the important bit when reading code.

Scenario 2:


Oh, I want to pick the current question - done.

Now I may have a moment of self doubt and go read the function’s definition to verify how this was actually accomplished but then I can blissfully forget about the implementation details. To me personally


is more valuable than

Map.put( :current_question, select_a_random_question(quiz) )

I would argue that


doesn’t really add enough value over

because build_substitution already heavily hints in that direction (and there isn’t much other noise on that line to begin with).

There is more noise in

Map.put( :current_question, select_a_random_question(quiz) ) 

for example it thrusts the implementation detail that the quiz contains a :current_question value in my face (which I probably should know if I work with it) - that together with select_a_random_question probably hints at pick_current_question - but I have to correlate these two separate pieces of information to come to that conclusion - reasoning overhead that


doesn’t require.


A few quick thoughts:

  • First, we didn’t invent this idea and there’s prior art to consult:
  • I liked your argument about us missing the case
  • Like everything, it’s a tradeoff you should use when it helps
  • I do find the Map.put interrupts my reading flow more than the, possibly because it feels more low level to me
  • Note that even in the version we used build_substitution for the real work (maybe it should have just been build_substitutions with included)
  • I really like how @peerreynders described the value of this technique: for me it’s about getting the function to tell a good story

This is something that I recently red about how the single level of abstraction principle can help to better structure the code, and make it easier to follow:

Hope this helps.


Thank you everyone for your responses.
I understand this is all about telling a good story. I guess this is what I am afraid of.

For example, I really like Tolkien (the auhtor) yet my partner doesn’t really like his stories. Some do, but prefer the cinema version which is widely different from the original (see The Hobbit book VS movies). My point is, everyone has a different idea of what a good story feels like. I have no doubt that experience plays a role when deciding to use this principle, it’s the subjective part I am afraid of :smiley:

Still, thank you everyone for your comments !

1 Like

As a simple example: this was my version of this.