Applying Single Level of Abstraction

Background

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

Code

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: 
  quiz
  |> 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:
    quiz
    |> 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:
    template.generators
    |> Enum.map(&build_substitution/1)
    |> 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:
    template.generators
    |> generate_substitutions()
    |> evaluate(template)

  defp generate_substitutions(%{substitution: _sub} = generator), do:
    Enum.map(&build_substitution/1)

However the authors choose not to do it.

Question

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?

2 Likes

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:

pick_current_question()

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

pick_current_question()

is more valuable than

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

I would argue that

generate_substitutions()

doesn’t really add enough value over

Enum.map(&build_substitution/1)

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

pick_current_question()

doesn’t require.

15 Likes

A few quick thoughts:

  • First, we didn’t invent this idea and there’s prior art to consult: http://principles-wiki.net/principles:single_level_of_abstraction
  • I liked your argument about us missing the Enum.map 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 Enum.map, possibly because it feels more low level to me
  • Note that even in the Enum.map version we used build_substitution for the real work (maybe it should have just been build_substitutions with Enum.map 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
7 Likes

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: https://aaronrenner.io/2019/09/18/application-layering-a-pattern-for-extensible-elixir-application-design.html

Hope this helps.

2 Likes

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.

2 Likes