Category: Design Principles

SLAP: Single Level of Abstraction Principle

Even though this acronym is quite catchy, SLAP is the one principle that you don’t find many people talking about.

Single Level of Abstraction

In essence, the principle proposes that each block of code should not mix what the code does with how it does it. Another way of thinking about it is, whenever possible, the code should describe in steps the actions that will take and then each step can elaborate on that.

For example:

class CreateTask(
private val clock: Clock,
private val localStorage: LocalStorage,
private val observers: List<TaskObserver>
) {
fun invoke(description: String) {
// normalize description
val normalizedDescription = if (description.length > MAX_DESCRIPTION_LENGTH)
description.substring(0, MAX_DESCRIPTION_LENGTH – 1) else
description
// create task
val currentTime = clock.now()
val initialStatus = Status.NotStarted
val newTask = Task(normalizedDescription, initialStatus, currentTime)
// save task
localStorage.save(newTask)
// notify
val observingNotStarting = mutableListOf<TaskObserver>()
for (i in 0..observers.size) {
val taskObserver = observers[i]
if (taskObserver.observedStatus == Status.NotStarted) {
observingNotStarting.add(taskObserver)
}
}
for (i in 0..observingNotStarting.size) {
observingNotStarting[i].notify(newTask)
}
}
}
view raw slap__many_levels.kt hosted with ❤ by GitHub

this class has one method that showcases both what it does and how it does it.

If we want to SLAP it we need to delegate the how of each step to its own method:

class CreateTask(
private val clock: Clock,
private val localStorage: LocalStorage,
private val observers: List<TaskObserver>
) {
fun invoke(description: String) {
val newTask = createNewTask(description)
localStorage.save(newTask)
notifyAnyObservers(newTask)
}
private fun createNewTask(description: String): Task {
val normalizedDescription = normalize(description)
return Task(normalizedDescription, Status.NotStarted, clock.now())
}
private fun normalize(description: String): String {
return if (description.length > MAX_DESCRIPTION_LENGTH)
description.substring(0, MAX_DESCRIPTION_LENGTH – 1) else
description
}
private fun notifyAnyObservers(newTask: Task) {
observers
.filter { taskObserver -> taskObserver.observedStatus == Status.NotStarted }
.forEach { taskObserver -> taskObserver.notify(newTask) }
}
}
view raw slap__one_level.kt hosted with ❤ by GitHub

here the invoke method simply describes what will happen upon its invocation. A new task will be created, then saved and finally passed to any observers.
For knowing how each step gets implemented we need to drill down one level. For example, creating a new task requires us to normalize the provided description and then create the task. For knowing how the normalization gets implemented we yet again move one level deeper!

Conclusion

Keep hiding how something gets implemented in new methods until you can no longer avoid it!

Don’t force your objects to construct what they need

Let’s say we have an object that handles instances of Person. For example PeopleScreen:

// Person.kt
class Person(
val name: String,
val surname: String
)
// PeopleScreen.kt
class PeopleScreen(
private val people: List<Person>
) {
fun render() {
people.forEachIndexed { index, person ->
println("${index + 1}. ${person.name}, ${person.surname}")
}
}
}
// Usage:
fun main() {
val people = listOf(
Person("Joe", "Dow"),
Person("Jill", "Doe"),
Person("Jack", "Black")
)
val screen = PeopleScreen(people)
screen.render()
}
view raw dont_force_construction__the_proper_way.kt hosted with ❤ by GitHub

PeopleScreen renders instances of Person so this should be the only format we provide to it. Let me explain.

Forced construction

There is a new flow that ends in opening PeopleScreen but all the information for the list of people are in a Map<String, String>. There is no reason to alter PeopleScreen in order to support this new format:

// Person.kt
class Person(
val name: String,
val surname: String
)
// PeopleScreen.kt
class PeopleScreen(
private val people: List<Person>
) {
constructor(people: Map<String,String>) : this(
people.map { entry -> Person(entry.key, entry.value) }
)
fun render() {
people.forEachIndexed { index, person ->
println("${index + 1}. ${person.name}, ${person.surname}")
}
}
}
// Usage:
fun main() {
val people = mapOf(
"Joe" to "Dow",
"Jill" to "Doe",
"Jack" to "Black"
)
val screen = PeopleScreen(people)
screen.render()
}
view raw dont_force_construction__the_forced_way.kt hosted with ❤ by GitHub
the new format is passed through an overloaded constructor but the same goes if we use a setter method

Why we shouldn’t do it

We could argue that by doing so we tie the object with each special format making the code hard to maintain and scale but the real reason is that we violate the SRP principle since PeopleScreen will have more than one reasons to change. One if something changes in the way we render and two if something changes in Person‘s construction.

What we should do

We should keep PeopleScreen only consuming Person and move all transformations to their own objects allowing a coordinator to transform and pass data around.