The “Tell, don’t ask” principle

This is one of my favorite principles because it is easy to spot when violated and because it helps in having proper API surfaces when applied.

Tell, don’t ask

In essence this principle proposes that instead of asking from an instance for its values in order to decide how the same instance will execute something, just tell the instance to execute it. It knows its own state, it can make its own decisions!

Asking

By asking we actually refer to accessing many of a class’s properties. For example:

	// somewhere in the code
	if (task.status == Status.NotStarted && task.createdAt < LocalDate.of(2021, 1, 14) && task.subscribers.isEmpty()) {
	task.close()
	}

	// which might have led to this API
	class Task(
	initialStatus: Status,
	val createdAt: LocalDate
	) {

	var status: Status = initialStatus
	private set

	private val innerSubscribers = mutableListOf<Subscriber>()
	val subscribers: List<Subscriber> = innerSubscribers

	fun add(subscriber: Subscriber) {
	innerSubscribers.add(subscriber)
	}

	fun close() {
	status = Status.Resolved
	}
	}

view raw tell_dont_ask__violation.kt hosted with ❤ by GitHub

in the code above we ask the task to provide the values of three of its properties in order to decide if we are going to close it or not.
In the process we (a) might had to expose those properties just for this code (creation date and subscribers could be private) and (b) inevitably leaked business logic that involves a task (when a task is eligible for closing).

Telling

Lets change the code in order to tell the task to close itself if possible:

	// somewhere in the code
	task.closeIfUnclaimed(createdBefore = LocalDate.of(2021, 1, 14))

	// task's better API
	class Task(
	initialStatus: Status,
	private val createdAt: LocalDate
	) {

	var status: Status = initialStatus
	private set

	private val subscribers = mutableListOf<Subscriber>()

	fun add(subscriber: Subscriber) {
	subscribers.add(subscriber)
	}

	fun closeIfUnclaimed(createdBefore: LocalDate): Boolean {
	if (status == Status.NotStarted && createdAt < createdBefore && subscribers.isEmpty()) {
	status = Resolved
	return true
	}

	return false
	}
	}

view raw tell_dont_ask__applied.kt hosted with ❤ by GitHub

There are two things that we gain from this change:

we moved the “closing” logic in the Task itself which allows us to contain future logic alterations in just one place.
the class’s API exposes only the necessary helping us to avoid accidental couplings.

LSP and ISP: The LI of SOLID

I am under the impression that every time I come across a SOLID post, LSP and ISP are not given the same amount of attention as the other three. I guess its because they are the easiest to grasp but make no mistake, they are also the easiest to violate!

Liskov Substitution Principle (LSP)

In essence, LSP proposes that we create sub-classes that can be used wherever their parents are being used without breaking or changing the client’s behavior.

This means that in the code snippet below:

	fun printSeniority(engineer: SoftwareEngineer, yearsInBusiness: Int) {
	val seniority = engineer.calculateSeniority(yearsInBusiness)
	val label = when (seniority) {
	SoftwareEngineer.JUNIOR -> "junior"
	SoftwareEngineer.MID -> "mid"
	else -> "senior"
	}

	println("This is a $label engineer")
	}

view raw lsp_isp__lsp_fun.kt hosted with ❤ by GitHub

we should be able to pass instances from all sub-classes of SoftwareEngineer without worrying that calculateSeniority will break or change the behavior of printSeniority.

Ways that we tend to violate LSP

By throwing an exception

	class MobileEngineer : SoftwareEngineer() {

	override fun calculateSeniority(yearsInBusiness: Int): Int {
	require(yearsInBusiness > 2)
	return super.calculateSeniority(yearsInBusiness)
	}
	}

view raw lsp_isp__lsp_throw.kt hosted with ❤ by GitHub

This is the obvious one. If, for example, the subclass adds a check that will eventually throw an exception then the client will break.

By returning undocumented results

	class MobileEngineer : SoftwareEngineer() {

	override fun calculateSeniority(yearsInBusiness: Int): Int {
	if (yearsInBusiness >= 15) {
	return ULTRA_SENIOR
	}
	return super.calculateSeniority(yearsInBusiness)
	}

	companion object {
	const val ULTRA_SENIOR = 3
	}
	}

	// which leads in:

	fun printSeniority(engineer: SoftwareEngineer, yearsInBusiness: Int) {
	val seniority = engineer.calculateSeniority(yearsInBusiness)
	val label = when (seniority) {
	MobileEngineer.ULTRA_SENIOR -> "ultra senior" // printSeniority is forced to know about MobileEngineer
	SoftwareEngineer.JUNIOR -> "junior"
	SoftwareEngineer.MID -> "mid"
	else -> "senior"
	}

	println("This is a $label engineer")
	}

view raw lsp_isp__lsp_know_more.kt hosted with ❤ by GitHub

In other words, the subclass returns something that the its parent never will.
This forces the client to know about the subclass which makes the code less scalable.

By having side effects

	class MobileEngineer(
	private val backend: Backend
	) : SoftwareEngineer() {

	override fun calculateSeniority(yearsInBusiness: Int): Int {
	return backend.calculateSeniority(yearsInBusiness)
	}
	}

view raw lsp_isp__lsp_network.kt hosted with ❤ by GitHub

This is the subtle one since it does not change the client’s code but it does change the expected behavior. printSeniority is expected to make a calculation and then print the result but know it also makes a network call!

Interface Segregation Principle (ISP)

In essence, ISP proposes that interfaces should not play the role of “methods bucket” because eventually there will be a client that will not need to implement all of them.

This means that interfaces like this:

	interface Repository {
	// db:
	fun select(id: Int): SoftwareEngineer?
	fun insert(engineer: SoftwareEngineer)

	// api:
	fun get(id: Int): SoftwareEngineer?
	fun post(engineer: SoftwareEngineer)
	}

	class LocalEngineersCache : Repository {

	override fun select(id: Int): SoftwareEngineer? {
	// actual implementation
	}

	override fun insert(engineer: SoftwareEngineer) {
	// actual implementation
	}

	override fun get(id: Int): SoftwareEngineer? {
	throw UnsupportedOperationException()
	}

	override fun post(engineer: SoftwareEngineer) {
	throw UnsupportedOperationException()
	}
	}

view raw lsp_isp__isp_all_in_one.kt hosted with ❤ by GitHub

should break in more meaningful parts and allow every client to implement only the part that it needs:

	interface Database {
	fun select(id: Int): SoftwareEngineer?
	fun insert(engineer: SoftwareEngineer)
	}

	interface Api {
	fun get(id: Int): SoftwareEngineer?
	fun post(engineer: SoftwareEngineer)
	}

	class LocalEngineersCache : Database {

	override fun select(id: Int): SoftwareEngineer? {
	// actual implementation
	}

	override fun insert(engineer: SoftwareEngineer) {
	// actual implementation
	}
	}

view raw lsp_isp__isp_broken.kt hosted with ❤ by GitHub

Its worth mentioning that this way, in addition from avoiding ISP violation we also:

Keep our code from violating the SRP.
In the first implementation, our cache depends in two things so it has more that one reasons to change (ex: a new parameter in the post method would force us to change our cache too)
Keep our code from violating the LSP. By having one interface, the first implementation of our cache couldn’t be used in code that expects repositories since its API methods would break the client.
Keep our code clean and scalable (the cache does not have to know about talking to the API)

Ways that we tend to violate ISP

Although there is not much to say here, since the only way to do it is by creating those buckets we mentioned above, beware of the creation since it comes in two flavors.
The first is by having all methods in one file. Easy to catch it in a PR review. The second though is by having an hierarchy in our interfaces.

	interface Load {
	fun load(): List<SoftwareEngineer>
	}

	interface LoadAndSave : Load {
	fun save(engineer: SoftwareEngineer)
	}

view raw lsp_isp__isp_hierarchy.kt hosted with ❤ by GitHub

By the time there is an implementation that does not need all methods, it might too late!

Avoid primitive obsession and build your own context

Primitive obsession is a known code smell that describes the usage of primitives for representing domain values. For example:

	class User(
	val name: String,
	val age: Int
	) {

	init {
	require(name.length in (2..25))
	require(age in (0..110))
	}
	}

view raw primitive_obsession__user_with_primitives.kt hosted with ❤ by GitHub

In this class both the user’s name and age are being represented by a string and an int respectively.

How else could we represent a name and an age?
Well, the primitives are the correct ones but not for direct usage. We can build value objects upon them and encapsulate both the meaning of the value and the business logic:

	class User(
	val name: Name,
	val age: Age
	)

	class Name private constructor(
	val value: String
	) {
	companion object {
	fun of(value: String): Name {
	require(value.length in (2..25))
	return Name(value)
	}
	}
	}

	class Age private constructor(
	val value: Int
	) {
	companion object {
	fun of(value: Int): Age {
	require(value in (0..110))
	return Age(value)
	}
	}
	}

view raw primitive_obsession__user_with_value_objects.kt hosted with ❤ by GitHub

So what? You just wrapped a primitive and moved the check.
True but now we have:

1. A reusable object

When the time comes and we need to have a new named entity we just use the class above and we can be sure that the business logic will follow along and be concise in the entire project.

2. Always valid instances

Whenever we see an instance of name or age we are certain that the instance holds a valid value. This means that an entity that consists from those value objects can only create valid instances and this means that the code that uses those entities (and value objects) does not need to have unnecessary checks. Cleaner code.

3. Code that scales more easily

Lets say that our business logic changes and we need to support users with invalid names too but without the need to deal with the name itself.
Having a value object can help implement the change easily. We just change the Name class. All other code remains the same:

	sealed class Name constructor(
	val value: String
	) {

	object UnknownName : Name("")

	class KnownName(value: String) : Name(value)

	companion object {
	fun of(value: String): Name {
	return if (value.length in (2..25))
	KnownName(value) else
	UnknownName
	}
	}
	}

view raw primitive_obsession__user_with_invalid_name.kt hosted with ❤ by GitHub

4. Code that is more robust

Lets say that our entities have the notion of an id and that after a few years the underline value needs to change from an integer to a long.
By having a value object to represent the Id all changes will take place in the outer layers of our architecture where we load/fetch ids from databases/network and create the id instances. The rest of project will remain untouched, especially the domain layer that holds our business logic.
If we had chosen the path of having an integer property in every entity then all of our entities, and the code that uses them, would need to change too.

5. Code that is more readable and reveals its usage

I’ve written a couple of posts in the past that showcase both the readability aspect and the revelation one.

6. A blueprint of our domain

When we open our project and see files like Invoice, Price, Quantity, Amount, Currency we get an immediate feel of what this project/package deals with and what are its building blocks.
We consume information that we would otherwise need to dig inside each file to find out.

7. A context

The final and most important part of having value objects is that now we can complete our entities and build a context for our domain. A common language that we can use to communicate with other engineers and stake holders in general.
Primitives are essential and they are the building blocks of a language but not of our business. The rest of company does not build its workflows upon integers and strings. It uses the businesses’ building blocks like age, name etc. It is vital that we do the same too in order to keep our code base in sync with the business.

IoC: Inversion of Control principle

This is the one principle that, chances are, you have applied even if you didn’t do it on purpose.
In essence, if you have written code that does not have any control over the execution flow, then you most probably have applied the IoC principle. How?

IoC through design patterns

If you have implemented the strategy or the template pattern then you have applied the IoC principle. For example, having a report generator and feeding it with the necessary filtering code.
All the code you write for filtering data, does not have any control over the execution’s flow. The generator is the one that decides when and if it will be invoked:

	class Report(
	val women: List<Person>,
	val men: List<Person>
	) {
	fun isEmpty(): Boolean {
	return women.isEmpty() && men.isEmpty()
	}
	}

	class ReportGenerator(
	private val repository: Repository
	) {

	fun create(filter: (Report) -> Report): Report {
	val people = repository.fetchAllPeople()

	val rawReport = splitByGender(people)
	if (rawReport.isEmpty()) {
	return rawReport
	}

	// the filter function does not have any control over its invokation
	val filteredReport = filter(rawReport)
	return sortByName(filteredReport)
	}

	// …
	}

	// example:
	val reportGenerator = ReportGenerator(repository)

	val withPeopleOver21 = { rawReport: Report ->
	val over21 = { person: Person -> person.age > 21 }
	Report(
	rawReport.women.filter(over21),
	rawReport.men.filter(over21)
	)
	}

	val reportWithPeopleOver21 = reportGenerator.create(withPeopleOver21)

view raw ioc__strategy_pattern.kt hosted with ❤ by GitHub

Strategy pattern

The same goes with the template pattern too. The code you write in the template’s hooks is being controlled by the template and you don’t get to control it:

	class Report(
	val women: List<Person>,
	val men: List<Person>
	) {
	fun isEmpty(): Boolean {
	return women.isEmpty() && men.isEmpty()
	}
	}

	abstract class ReportGenerator(
	private val repository: Repository
	) {

	fun create(): Report {
	val people = repository.fetchAllPeople()

	val rawReport = splitByGender(people)
	if (rawReport.isEmpty()) {
	return rawReport
	}

	val filteredReport = filter(rawReport)
	return sortByName(filteredReport)
	}

	abstract fun filter(report: Report): Report

	// …
	}

	class AdultsReportGenerator(repository: Repository) : ReportGenerator(repository) {

	override fun filter(report: Report): Report {
	val over21 = { person: Person -> person.age > 21 }
	return Report(
	report.women.filter(over21),
	report.men.filter(over21)
	)
	}
	}

	// example:
	val generator = AdultsReportGenerator(repository)
	val reportWithPeopleOver21 = generator.create()

view raw ioc__template_pattern.kt hosted with ❤ by GitHub

Template pattern

Both of these examples might seem weird since we are the ones that wrote both the filtering code and the generator so we feel that we control the flow. The thing is that we need to separate them in our heads and observe them individually. The generator is the one that controls the flow and dictates the actions that will take place. The filtering code is one of the actions. We just write them, provide them to the generator and that’s it.

IoC through frameworks

Another way of applying IoC is by using frameworks that have adopted it. Most popular are the IoC containers that are used to inject dependencies.
Another example is the android’s framework. In android you don’t have control over an activity’s lifecycle and you simply extend the Activity class and override hooks to run your code.

IoC vs DI

Because of the aforementioned IoC containers, many people assume that dependency injection and IoC are the same. They are not. DI is just a way to help in applying the IoC principle. For example:

	class Report(
	val women: List<Person>,
	val men: List<Person>
	) {
	fun isEmpty(): Boolean {
	return women.isEmpty() && men.isEmpty()
	}
	}

	class ReportGenerator(
	private val repository: Repository,
	private val filter: (Report) -> Report
	) {

	fun create(): Report {
	val people = repository.fetchAllPeople()

	val rawReport = splitByGender(people)
	if (rawReport.isEmpty()) {
	return rawReport
	}

	val filteredReport = filter(rawReport)
	return sortByName(filteredReport)
	}

	// …
	}

	// Example:
	val withPeopleOver21 = { report: Report ->
	val over21 = { person: Person -> person.age > 21 }
	Report(
	report.women.filter(over21),
	report.men.filter(over21)
	)
	}

	val generator = ReportGenerator(repository, withPeopleOver21)
	val reportWithPeopleOver21 = generator.create()

view raw ioc__dependency_injection.kt hosted with ❤ by GitHub

we can change the generator and have the filtering code being injected to it by constructor. The inversion is already happening, DI is simply used to provide the extra code.

The memento design pattern in Kotlin

I started playing with the memento pattern for a use case I was researching when I realized that the Kotlin implementation had a, potentially, show stopper in comparison with the Java one:

I could not use a private property from within the same file

Why was that a show stopper? We’ll see, but first, what is the memento pattern?

Memento pattern

This pattern is a good way to implement a functionality that helps in restoring previous states. One good example is the undo in our text editors. You can write, edit, delete and then, by hitting undo, take each action back.

There are three main ingredients for this pattern:

the originator that holds the current state and creates snapshots of itself,
the memento that, in essence, is the snapshot with perhaps some additional metadata and
the caretaker that orchestrates the backup/restore of the state

So in our example the originator is the editor which knows what the text is, the carets position etc, the memento a copy of those values and the caretaker can be the interface between the user and the editor.

Java implementation

Lets try to have an overly simplified version of the above example in Java:

	public final class Editor {

	private final List<String> text;
	private int caretPosition;

	public Editor() {
	this.text = new ArrayList<>();
	this.caretPosition = 0;
	}

	public void write(final String sentence) {
	text.add(sentence);
	caretPosition = calculateCaretPositionInEndOf(text);
	}

	public void edit(final int index, final String newSentence) {
	text.remove(index);
	text.add(index, newSentence);
	final List<String> subText = text.subList(0, index + 1);
	caretPosition = calculateCaretPositionInEndOf(subText);
	}

	public void delete(final int index) {
	final List<String> subText = new ArrayList<>(text.subList(0, index));
	text.remove(index);
	caretPosition = calculateCaretPositionInEndOf(subText);
	}

	public void render(final Screen screen) {
	final String allText = String.join("", text);
	screen.render(allText);
	screen.renderCaretAt(caretPosition);
	}

	public Memento backup() {
	return new Memento(text, caretPosition);
	}

	public void restore(final Memento memento) {
	text.clear();
	text.addAll(memento.text);
	caretPosition = memento.caretPosition;
	}

	private int calculateCaretPositionInEndOf(final List<String> lines) {
	return lines.stream().mapToInt(String::length).sum() + 1;
	}

	public static final class Memento {

	private final List<String> text;
	private final int caretPosition;

	public Memento(List<String> text, int caretPosition) {
	this.text = new ArrayList<>(text);
	this.caretPosition = caretPosition;
	}
	}
	}

view raw memento__originator_memento_in_java.java hosted with ❤ by GitHub

Here the editor, besides manipulating text, is able to produce snapshots of its state in a way that only itself can access the state’s values. The Memento class might be public, in order to allow the caretaker to handle instances of it, but its fields are private and only the originator can read them.
A great way to copy something while having the smallest possible API surface and maximum privacy.

As a matter of fact, here is the caretaker and its usage:

	class UI(
	private val screen: Screen
	) {

	private val editor = Editor()
	private val backups = mutableListOf<Memento>()

	fun write(text: String) {
	backups.add(0, editor.backup())
	editor.write(text)
	editor.render(screen)
	}

	fun edit(index: Int, text: String) {
	backups.add(0, editor.backup())
	editor.edit(index, text)
	editor.render(screen)
	}

	fun delete(index: Int) {
	backups.add(0, editor.backup())
	editor.delete(index)
	editor.render(screen)
	}

	fun undo() {
	val memento = backups.removeAt(0)
	editor.restore(memento)
	editor.render(screen)
	}
	}

	fun main() {
	val screen = StdoutScreen()
	val ui = UI(screen)

	with(ui) {
	write("Hello, there! ")
	write("How are you? ")
	write("I hope you feel good :)")
	edit(1, "Kotlin! ")
	delete(1)
	undo()
	undo()
	undo()
	undo()
	undo()
	}
	}

	/* which produces this:
	Hello, there! \|
	Hello, there! How are you? \|
	Hello, there! How are you? I hope you feel good :)\|
	Hello, there! Kotlin! \|I hope you feel good 🙂
	Hello, there! \|I hope you feel good 🙂
	Hello, there! Kotlin! \|I hope you feel good 🙂
	Hello, there! How are you? I hope you feel good :)\|
	Hello, there! How are you? \|
	Hello, there! \|
	\|
	/*

view raw memento__caretaker_usage.kt hosted with ❤ by GitHub

As you can see the UI uses the editor to write, edit, delete but before that it saves a backup with the editor’s state in order to restore it every time the user hits undo!

Kotlin implementation

So lets move originator and memento to Kotlin. Ctrl+Alt+Shift+K and boom.. we have a problem:

Kotlin, in contrast with Java, does not allow accessing private properties when in the same file.

What do we do? Well we can always make the properties public:

	class Memento(text: List<String>, caretPosition: Int) {
	val text: List<String>
	val caretPosition: Int

	init {
	this.text = ArrayList(text)
	this.caretPosition = caretPosition
	}
	}

view raw memento__memento_with_public_properties.kt hosted with ❤ by GitHub

but this way we, indirectly, expose the editors state:

Another way to implement the pattern is to have Memento as an interface with no state for the public API and have a private implementation of it for internal usage:

	class Editor {

	// …

	fun backup(): Memento {
	return ActualMemento(text, caretPosition)
	}

	fun restore(memento: Memento) {
	if (memento !is ActualMemento) return

	text.clear()
	text.addAll(memento.text)
	caretPosition = memento.caretPosition
	}

	// …

	interface Memento

	private class ActualMemento(text: List<String>, caretPosition: Int) : Memento {
	val text: List<String>
	val caretPosition: Int

	init {
	this.text = ArrayList(text)
	this.caretPosition = caretPosition
	}
	}
	}

view raw memento__memento_with_interface.kt hosted with ❤ by GitHub

this way we do not expose any state but we do open a bit our API. We now have an interface that can be implemented and given to the restore() function.

Inner classes

Fortunately Kotlin has inner classes. An inner class can access the outer class’s members but, most importantly, can be extended only from within the outer class. This means that this:

	class Editor {

	// …

	fun backup(): Memento {
	return ActualMemento(text, caretPosition)
	}

	fun restore(memento: Memento) {
	memento as ActualMemento

	text.clear()
	text.addAll(memento.text)
	caretPosition = memento.caretPosition
	}

	// …

	open inner class Memento

	private inner class ActualMemento(text: List<String>, caretPosition: Int) : Memento() {
	val text: List<String>
	val caretPosition: Int

	init {
	this.text = ArrayList(text)
	this.caretPosition = caretPosition
	}
	}
	}

view raw memento__memento_with_inner_class.kt hosted with ❤ by GitHub

checks all our boxes. We keep the originator’s state private and our overall API small!

Test doubles: dummies, stubs, mocks, fakes

While testing we tend to replace some of the unit’s collaborators with mocks as it is accustomed to call them. The problem with that name is that it is not accurate. The real name of those mocks is test doubles and there are four of them with mock being one of the types.

One reason for this misnaming is the wide usage of mocking frameworks that do not separate the types between them (I am looking at you mockito).

So, lets try to define the four types and see when it is best to use them. We will be using a made up browser and its history and will not use any framework. Just theory:

	interface History {
	fun push(url: URL)
	fun pop(): URL
	fun peek(): URL
	}

	class Browser(
	private val history: History
	) {

	var activeURL: URL? = null
	private set

	fun visit(url: URL) {
	activeURL = if (url == URL("http://default"))
	history.peek() else
	url
	history.push(activeURL!!)
	}

	fun back() {
	history.pop()
	activeURL = history.peek()
	}
	}

view raw test_doubles__usecase.kt hosted with ❤ by GitHub

Dummies

A dummy is the test double that we use whenever we know that the collaborator will not be used:

	@Test fun `a newly created browser does not have an active URL`() {
	val browser = Browser(dummyHistory)

	assertThat(browser.activeURL, absent())
	}

	@Test fun `a visited URL is an active URL`() {
	val browser = Browser(dummyHistory)

	browser.visit(URL("https://www.le0nidas.gr"))

	assertThat(browser.activeURL, equalTo(URL("https://www.le0nidas.gr")))
	}

	private val dummyHistory = object : History {
	override fun push(url: URL) {

	}

	override fun pop(): URL {
	TODO("Not yet implemented")
	}

	override fun peek(): URL {
	TODO("Not yet implemented")
	}
	}

view raw test_doubles__dummies.kt hosted with ❤ by GitHub

For example in the tests above we just need to check the browser’s active URL. We know that this does not evolve the browser’s history so we pass a collaborator that does nothing on every method call.

Stubs

A stub is the test double that we use whenever the collaborator is being used to query values:

	@Test fun `if the visited URL is the default then redirect to the last visited from the browser's history`() {
	val browser = Browser(StubHistory(lastVisited = URL("https://www.le0nidas.gr")))

	browser.visit(URL("http://default"))

	assertThat(browser.activeURL, equalTo(URL("https://www.le0nidas.gr")))
	}

	private class StubHistory(
	private val lastVisited: URL
	) : History {
	override fun push(url: URL) {

	}

	override fun pop(): URL {
	TODO("Not yet implemented")
	}

	override fun peek(): URL {
	return lastVisited
	}
	}

view raw test_doubles__stubs.kt hosted with ❤ by GitHub

For example in the test above we feed the browser with a pre-populated history since we know that the browser will need to peek for the last visited URL.

Mocks

A mock is the test double that we use whenever the collaborator is being used to perform an action:

	@Test fun `every visited URL gets saved to the browser's history`() {
	val mockHistory = MockHistory()
	val browser = Browser(mockHistory)

	browser.visit(URL("https://www.le0nidas.gr"))

	mockHistory.verifySavedUrlIs(expectedURL = URL("https://www.le0nidas.gr"))
	}

	private class MockHistory : History {

	private var savedURL: URL? = null

	override fun push(url: URL) {
	savedURL = url
	}

	override fun pop(): URL {
	TODO("Not yet implemented")
	}

	override fun peek(): URL {
	TODO("Not yet implemented")
	}

	fun verifySavedUrlIs(expectedURL: URL) {
	assertThat(savedURL, equalTo(expectedURL))
	}
	}

view raw test_doubles__mocks.kt hosted with ❤ by GitHub

For example in the test above we need to make sure that the browser saves the provided URL to its history so we use a collaborator that can verify this behavior.

Fakes

A fake is the test double that we use whenever we need the collaborator to provide us a usable business logic:

	@Test fun `going back restores the previously visited URL`() {
	val browser = Browser(FakeHistory())
	browser.visit(URL("https://www.le0nidas.gr"))
	browser.visit(URL("https://www.google.com"))

	browser.back()

	assertThat(browser.activeURL, equalTo(URL("https://www.le0nidas.gr")))
	}

	private class FakeHistory : History {

	private val urls = mutableListOf<URL>()

	override fun push(url: URL) {
	urls.add(0, url)
	}

	override fun pop(): URL {
	return urls.removeAt(0)
	}

	override fun peek(): URL {
	return urls[0]
	}
	}

view raw test_doubles__fakes.kt hosted with ❤ by GitHub

For example in the test above we need a history instance that works as expected (a simple stack) but without the hassle of having a database or using the file system.

Final thoughts

Having your own test doubles per case makes the code simpler and more readable but does that mean that we should remove our mocking frameworks? In my opinion no. Having a framework saves you a lot of time and keeps things consistent, especially in big projects with lots of developers.

Knowing the theory behind something is always good since it lays a common foundation for discussions and decisions. A mix of the two, framework and theory, could be achieved and help the test code in readability.
For example, we can keep using Mockito’s mock but name the variable stubBlahBlah if is used as a stub. This way the reader will know what to expect.

PS #1: Spock testing framework, besides being a great tool, provides a way to separate stubs from mocks not just in semantics but in usage too (ex: you cannot verify something when using a stub)

PS #2: There is another type of test double called Spy which is a toned down mock that helps in keeping state when a certain behavior takes place but does not verify it.

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!

I prefer not to use the keyword “it”

And the reason is simple:

I want to be as explicit as possible and allow the reader of my code to have an uninterrupted flow.

Think about it. Every time you encounter the it keyword you do, a quick, conversion between what you see and what it represents. Personally I do it even in very small lambdas, imagine if you are two or three lines deep in a lambda and you see an it:

	val animals = listOf("Lion", "Penguin", "Giraffe", "Whale", "Shark")

	val usernames = animals.map {
	val randomNumber = Random.nextInt(0, 10)
	val randomCharacter = listOf("!", "@", "$", "%", "#")[Random.nextInt(0, 5)]
	"$it$randomCharacter$randomNumber"
	}

view raw prefer_not_using_it__non_usage.kt hosted with ❤ by GitHub

It might not look much in this simple example but read it now with an explicit value:

	val animals = listOf("Lion", "Penguin", "Giraffe", "Whale", "Shark")

	val usernames = animals.map { animalAsBase ->
	val randomNumber = Random.nextInt(0, 10)
	val randomCharacter = listOf("!", "@", "$", "%", "#")[Random.nextInt(0, 5)]
	"$animalAsBase$randomCharacter$randomNumber"
	}

view raw prefer_not_using_it__usage.kt hosted with ❤ by GitHub

You don’t have to do a mental translation and it also provides some details regarding the format of username.

This last part can make the code even more readable since it allows us to describe the values we use:

values.map { rawValue -> Name.of(rawValue) }

view raw prefer_not_using_it__usage_2.kt hosted with ❤ by GitHub

this hints that (a) values list does not contain usable data and (b) the of function will perform some kind of cleaning

Don’t share constants between production and test code

Building upon my previous post and the trick of being specific in the values the code respects, one pattern that I’ve noticed which can easily lead in many false positive tests is sharing a constant value between production and test code.

If the test code reads the value from the production, any change that was done by mistake will not affect the test which will continue to pass!

21 yeas of age

Lets say that we have two services, one checks if a customer can enter a casino and the other if she can buy alcohol. For both cases the law states that the minimum legal age is 21 years old.

The code has a configuration file, a domain and two modules for each service:

	// Production code:

	// configuration
	object Config {
	const val MIN_LEGAL_AGE = 21
	}

	// domain
	class Person(val age: Int)

	// entrance module
	fun canEnterCasino(person: Person): Boolean {
	return person.age >= Config.MIN_LEGAL_AGE
	}

	// alcohol module
	fun canBuyAlcohol(person: Person): Boolean {
	return person.age >= Config.MIN_LEGAL_AGE
	}

	// Test code:

	// entrance module
	fun `a customer can enter the casino when she is older than 21 years of age`() {
	val twentyOneYearOld = Person(Config.MIN_LEGAL_AGE)

	val actual = canEnterCasino(twentyOneYearOld)

	assertTrue(actual)
	}

	// alcohol module
	fun `a customer can buy alcohol when she is older than 21 years of age`() {
	val twentyOneYearOld = Person(Config.MIN_LEGAL_AGE)

	val actual = canBuyAlcohol(twentyOneYearOld)

	assertTrue(actual)
	}

view raw dont_share_constants__sharing.kt hosted with ❤ by GitHub

As you can see the tests consume the minimum age directly from the production code but the test suite passes, life is good.

Then one day, the law changes and the minimum legal age for entering a casino drops to 20 years! Simple change, not much of a challenge for the old timers so the task is being given to the new teammate who does not know all modules yet and is also a junior software engineer.
She sees the test, changes the value in the name to 20, sees the config, changes the constant’s value to 20, runs the test suite, everything passes, life is good! Only that it isn’t because the casino’s software now allows selling alcohol to 20 year olds!

Keep them separate

If the test code did not use the production’s code

	// Production code:

	// configuration
	object Config {
	const val MIN_LEGAL_AGE = 20
	}

	// domain
	class Person(val age: Int)

	// entrance module
	fun canEnterCasino(person: Person): Boolean {
	return person.age >= Config.MIN_LEGAL_AGE
	}

	// alcohol module
	fun canBuyAlcohol(person: Person): Boolean {
	return person.age >= Config.MIN_LEGAL_AGE
	}

	// Test code:

	// entrance module
	fun `a customer can enter the casino when she is older than 20 years of age`() {
	val twentyOneYearOld = Person(20)

	val actual = canEnterCasino(twentyOneYearOld)

	assertTrue(actual) // passed
	}

	// alcohol module
	fun `a customer can buy alcohol when she is older than 21 years of age`() {
	val twentyOneYearOld = Person(21)

	val actual = canBuyAlcohol(twentyOneYearOld)

	assertTrue(actual) // failed
	}

view raw dont_share_constants__not_sharing.kt hosted with ❤ by GitHub

then, after changing the constant’s value, the test suite would fail alerting the software engineer that something has broken forcing her to figure it out and craft another solution.

Your tests can also be your documentation

Tests help as make sure that our code works, provide us a safety net when we need to refactor and, when having proper test names, can be a good documentation describing what the code does.
The last one can be especially helpful for both newcomers that need to understand the system and old timers that haven’t visited the code for a while!

A couple of tricks for achieving good names are:

Avoid describing how the code does something and try to describe what it does
For example:
calling add(item) results in calling recalculate
is way too specific without providing anything meaningful, or anything that we wouldn’t get from reading the code.
On the other hand:
a recalculation of the order's value takes place every time a new item gets added
shares an important information about the Order‘s behavior when adding an item.
Avoid being too abstract
For example:
a customer can buy alcohol when she is of legal age
can help the reader understand how the code behaves but in a documentation you need specific values.
So:
a customer can buy alcohol when she is older than 21 years of age
is much better because it also provides the exact threshold that our code considers for allowing someone to buy alcohol