Fl4m3Ph03n1x
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:
- The
Map.putdeals with Elixir basic data types (map) - 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:
- It adds a level of indirection
- 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:
- Enumerable data types from elixir
- 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?
Most Liked
peerreynders
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.
JEG2
A few quick thoughts:
- First, we didn’t invent this idea and there’s prior art to consult: Single Level of Abstraction (SLA) [Principles Wiki]
- I liked your argument about us missing the
Enum.mapcase - Like everything, it’s a tradeoff you should use when it helps
- I do find the
Map.putinterrupts my reading flow more than theEnum.map, possibly because it feels more low level to me - Note that even in the
Enum.mapversion we usedbuild_substitutionfor the real work (maybe it should have just beenbuild_substitutionswithEnum.mapincluded) - I really like how @peerreynders described the value of this technique: for me it’s about getting the function to tell a good story
djantea
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.
Popular in Discussions
Other popular topics
Latest on Elixir Forum
Sponsor Spotlight
Producing high quality Elixir screencasts since 2017.
Categories:
Sub Categories:
Forums
Popular Tags
- #ecto
- #liveview
- #troubleshooting
- #learning-elixir
- #deployment
- #library
- #erlang
- #testing
- #genserver
- #mix
- #absinthe
- #remote-other
- #otp
- #plug
- #how-to-question
- #macros
- #postgres
- #channels
- #elixirconf
- #exunit
- #discussion
- #code-sync
- #javascript
- #podcasts
- #onsite
- #dialyzer
- #docker
- #authentication
- #umbrella
- #full-time-contract
- #podcasts-by-brainlid
- #ecto-query
- #elixir-ls
- #phoenix_html
- #iex
- #blog-post
- #graphql
- #genstage
- #ai
- #websockets
- #supervisor
- #advent-of-code
- #elixirconf-us
- #distillery
- #processes
- #forms
- #api
- #metaprogramming
- #security
- #performance
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Real-time error tracking, performance insights, and observability for devs.
Practical resources that improve the lives of professional developers.
Enabling companies to succeed by building software people love.
The deployment platform built for Elixir: PaaS ease, VPS control.
Courses that'll move you from confusion to "Aha, now I get it!"