Two reasons why you should add a return type in your functions in Kotlin

Kotlin’s compiler is clever enough to figure out on its own what is the return type of a function but this does not mean that we should over use it and here is why:

Help the compiler to help us

By adding a return type in a function we instruct the compiler to expect and force that type (by a compiler error). On the other hand if we allow the compiler to infer the type, if something changes in the function’s body and the return type is not the one intended by the author, the compiler will follow along thinking that we know what we are doing!

Help the reader [to help us]

We write something once but it gets read multiple times. So it is our responsibility to make it as readable, explicit and quick in the eye as we can. In every case that we omit a return type the reader of our code has to do the calculations and extract the type on her own which, depending on the complexity, will take time and effort. You might say that a few seconds is not a big deal but in comparison with the zero seconds of having a type it is a lot.

Also not all reading takes place in an IDE that provides hints and colorful help. Our PR reviewers will probably read out code directly from GitHub or GitLab. By making them change context to figure something out we break their flow and concentration.

So, when should we use it

~~Never!~~ In my humble opinion the only valid place is in small (one line), private methods that either construct something, so the use of the constructor along side the = sign trick the mind:

private fun createName(value: String) = Name(value)

view raw use_return_type__createname.kt hosted with ❤ by GitHub

or the return type is clearly obvious:

private fun isCompleted(task: Task) = task.status in listOf(COMPLETED, CANCELLED)

view raw use_return_type__iscompleted.kt hosted with ❤ by GitHub

A use case of using chain of responsibility pattern to scale strategy

Lets say we have a simple application that executes certain actions dictated by an external service.

More particular the external service sends a response that looks like this:

	class Response(
	val action: String,
	val value: String
	)

view raw response_first_iteration.kt hosted with ❤ by GitHub

the supported actions are:

	interface Action {
	val name: String
	fun execute(response: Response)
	}

	class Print : Action {

	override val name: String = "print"

	override fun execute(response: Response) {
	println("printing ${response.value}…")
	}
	}

	class Log : Action {

	override val name: String = "log"

	override fun execute(response: Response) {
	println("logging ${response.value}…")
	}
	}

	class WriteToFile : Action {

	override val name: String = "write_to_file"

	override fun execute(response: Response) {
	println("writing to file ${response.value}…")
	}
	}

view raw actions_first_iteration.kt hosted with ❤ by GitHub

and there is an executor to help as translate the response to an actual action execution:

	class ActionExecutor {

	private val allActions = mutableMapOf<String, Action>()

	fun addAction(action: Action) {
	allActions[action.name] = action
	}

	fun executeByResponse(response: Response) {
	val action = allActions[response.action]
	action?.execute(response)
	}
	}

view raw action_executor_first_iteration.kt hosted with ❤ by GitHub

This is an implementation of the Strategy Pattern where every strategy is a certain action allowing us to add as many actions as we want as long as there is a one-to-one relation with what the response sends:

	fun main() {
	val executor = createActionExecutor()

	executor.executeByResponse(Response("print", "leonidas"))
	executor.executeByResponse(Response("log", "kotlin"))
	executor.executeByResponse(Response("write_to_file", "leonidas loves kotlin"))
	}

	private fun createActionExecutor(): ActionExecutor {
	return ActionExecutor().apply {
	addAction(Print())
	addAction(Log())
	addAction(WriteToFile())
	}
	}

view raw main_first_iteration.kt hosted with ❤ by GitHub

The problem

One day the external service decides to add a print error action but it does not do it by having a new action value. Instead it decides to have an is error flag which must be taken under consideration when the action value is print!

So the response is now this:

	class Response(
	val action: String,
	val value: String,
	val isError: Boolean = false
	)

view raw response_second_iteration.kt hosted with ❤ by GitHub

leading us into having an if in the print action’s code

	class Print : Action {

	override val name: String = "print"

	override fun execute(response: Response) {
	if (response.isError) {
	System.err.println("printing (in error stream) ${response.value}…")
	return
	}
	println("printing ${response.value}…")
	}
	}

view raw print_second_iteration.kt hosted with ❤ by GitHub

which defeats the purpose of the strategy pattern and violates the SRP. Each strategy should do one thing and one thing only. By having an if in the strategy we allow it to implement two actions thus having two reasons to change.

Adding a chain

What we need is a way to allow the representation of a single action value from multiple strategies where each one implements a unique action depending on the values of the response.

This is where the Chain of Responsibility Pattern comes in helping as into having multiple actions tied together, passing the response to each other until one of them can execute it.

There are two ways to implement the pattern depending on the size and state of your project.

Using inheritance

If you have a small project with just a few actions and you don’t mind touching many files you can use inheritance and have each action containing the next in the chain:

	abstract class BaseAction(
	private val nextAction: Action?
	) : Action {

	override fun execute(response: Response) {
	nextAction?.execute(response)
	}
	}

	class Print : Action {

	override val name: String = "print"

	override fun execute(response: Response) {
	println("printing ${response.value}…")
	}
	}

	class PrintInErrorStream(
	nextAction: Action?
	) : BaseAction(nextAction) {

	override val name: String = "print"

	override fun execute(response: Response) {
	if (response.isError) {
	System.err.println("printing (in error stream) ${response.value}…")
	return
	}
	super.execute(response)
	}
	}

view raw cof_inheritance.kt hosted with ❤ by GitHub

which can be used as such:

	fun main() {
	val executor = createActionExecutor()

	executor.executeByResponse(Response("print", "leonidas"))
	executor.executeByResponse(Response("log", "kotlin"))
	executor.executeByResponse(Response("write_to_file", "leonidas loves kotlin"))
	executor.executeByResponse(Response("print", "$&#$@#", isError = true))
	}

	private fun createActionExecutor(): ActionExecutor {
	return ActionExecutor().apply {
	addAction(PrintInErrorStream(Print())) // first try to print in error and the in simple
	addAction(Log())
	addAction(WriteToFile())
	}
	}

view raw main_cor_inheritance.kt hosted with ❤ by GitHub

Using composition

If we do not wish to change any of the existing actions then composition is the only way.

What we need is a way to wrap an existing action in an object that will (a) hold the next action in the chain and (b) decide which action will be executed, the wrapped or the next one:

	class ChainAction(
	private val action: Action,
	private val canExecute: (Response) -> Boolean
	) : Action {

	private var nextAction: Action? = null
	override val name: String = action.name

	override fun execute(response: Response) {
	if (canExecute(response)) {
	action.execute(response)
	return
	}

	nextAction?.execute(response)
	}

	fun or(action: ChainAction): ChainAction {
	nextAction = action
	return this
	}
	}

	fun Action.asChain(canExecute: (Response) -> Boolean): ChainAction =
	ChainAction(this, canExecute)

view raw chain_action.kt hosted with ❤ by GitHub

Using ChainAction results in this:

	fun main() {
	val executor = createActionExecutor()

	executor.executeByResponse(Response("print", "leonidas"))
	executor.executeByResponse(Response("log", "kotlin"))
	executor.executeByResponse(Response("write_to_file", "leonidas loves kotlin"))
	executor.executeByResponse(Response("print", "$&#$@#", isError = true))
	}

	private fun createActionExecutor(): ActionExecutor {
	val printInErrorStream = PrintInErrorStream().asChain { response -> response.isError }
	val justPrint = Print().asChain { true }

	return ActionExecutor().apply {
	addAction(printInErrorStream.or(justPrint))
	addAction(Log())
	addAction(WriteToFile())
	}
	}

view raw main_cor_composition.kt hosted with ❤ by GitHub

This way we can scale the strategy pattern both vertically, one strategy per action value, and horizontally, one strategy per action value sub cases.

I wrote a GitHub Action using Kotlin

I decided to take a look at GitHub Actions so for the past week I’ve been watching and reading everything about it. I even wrote a post, an Introduction to GitHub Actions. What I found really interesting is the fact that you can write an action using the language you feel more comfortable with. And so I did!

I wrote a small action that:

collects all the changed files from a PR,
keeps those that have the .kt suffix,
runs ktlint on them and
makes a comment in the PR for every error that ktlint reports

and all that using Kotlin and some bash!

You can find and use it here: ktlint-pr-comments

GitHub Action using Docker

There are three ways to create an action but only the one using Docker allows us to use the language we want.

In all three ways the main two ingredients are:

the action’s code
the action’s metadata, a file called action.yml which is placed in the root folder of your project and defines how the action will run and what inputs/outputs it has.

In our case there is also a third ingredient, a Dockerfile or a docker image which is used by the action’s runner to create a container and execute the action’s code inside it. All you have to do is to make sure that the action’s executable parts are being copied in the container and that are called upon its start.

The runner makes sure that the working space is being mounted to the container (in the state that it was just before the action is started) along with all the environment variables and the inputs the action needs. You can read more in the documentation.

Ktlint PR comments

Action’s code

The action has three distinct parts.

The first part is responsible for using GitHub’s REST API to collect all of the PR’s changes and then keep those that are in Kotlin files and were added or modified. For that I used kscript and I was able to leverage all the libraries that I was accustomed to, like Retrofit and Moshi. When I was happy with the resulted script I used its --package option to create a standalone binary and copy it in the action’s Docker image.

The second part is a combination of bash commands that execute the ktlint binary by passing to it the results of the first part. Ktlint is being called with the --reporter=json parameter in order to create a JSON report.

The third and final part is again a kscript script that uses the report created before and GitHub’s REST API to make a PR line comment for every ktlint error that is part of the PR’s diff. Again a standalone binary was created and put in the image.

Note:

I like kscript since I can write things fast, easy and with all the libraries that I know but I also like writing test first and that proved to be quite difficult. So what I ended up doing was to act as if I was in a Kotlin project. I created my tests (using all my favorites like junit5, hamkrest and MockWebServer) and from that I created .kt files with the proper functionality. And for having a script I created a .kts file where I defined the external dependencies and included the .kt files:

	import kotlin.system.exitProcess

	//DEPS com.squareup.moshi:moshi:1.9.3
	//DEPS com.squareup.moshi:moshi-kotlin:1.9.3
	//DEPS com.squareup.retrofit2:retrofit:2.9.0
	//DEPS com.squareup.retrofit2:converter-moshi:2.9.0

	//INCLUDE logging.kt
	//INCLUDE common.kt
	//INCLUDE collectPrChanges.kt
	//INCLUDE createGithubEvent.kt

	val result = collectPrChanges(args)

	if (result != 0) {
	exitProcess(result)
	}

	println("Changes collected")

view raw exec-kscript.kts hosted with ❤ by GitHub

Action’s metadata

From the start what I wanted for this action was to be as autonomous as possible leaving very little responsibilities to the consumer and allowing her to just plug it in and watch it play.

For that the only input the action needs is a token, for allowing the kscript scripts to communicate with the API, which will most likely be the default secrets.GITHUB_TOKEN making the action’s usage as simple as adding the following lines in your workflow:

- uses: le0nidas/ktlint-pr-comments@v1
  with:
    repotoken: ${{ secrets.GITHUB_TOKEN }}

Docker image

A lot of things must happen in order to have the action ready to run. Sdkman, Kotlin and kscript must be installed, the code needs to be retrieved from the repository and both kscript scripts have to be packaged. On top of that ktlint must be downloaded and placed in the proper path.

For all that, and to shave a few seconds from the action, I decided to have an image that has everything ready. So I created a workflow that gets triggered every time there is a push in the main branch, builds and packs everything in an image and pushes the result to Docker Hub.

So now the action simply uses that image to run a container without any other ceremonies.

Note:

Before using Docker Hub I tried to use GitHub Packages but it turns out that public is not that public^* since it requires an authentication to retrieve a package.

Summary

That’s it! An action for having ktlint’s report as comments in your PR. A result of trial and error since I wrote it while learning about actions but I hope that someone might find it useful. If you do let me know!

An example of how to use it can be found in the action’s repository where I dogfood it to the project.

* [3 Sep 2020]: looks like things will change

Know your tools: scratch files in IntelliJ IDEA

I’ve used scratch files in IntelliJ IDEA and Android Studio but I think that can be found in all of Jetbrain’s products.

What are they?

Scratch files are files that don’t get tracked by the version control system, can be created at any given time and, most importantly, get bind to the IDE and not the project that is currently open.

How do I create them?

The simplest way is to hit ctrl+alt+shift+insert. If you can’t remember it press shift twice and start writing scratch, you will be presented with the action of creating a new one.

The next step is to choose what kind of file you want to create and this is where it gets interesting since you can choose from a plethora of file types. From plain text, to markdown, Kotlin, JSON, XML, ruby and many many more!

How do I use them?

By choosing the file’s type you choose how the IDE will behave when you are working on it, so if you create a scratch.json and paste some json in it you can format it accordingly. Or if you create a scratch.md you can start writing in markdown and have a preview of your work.

But the most powerful aspect of those files is when you create code related ones. If, for example, you create a scratch.kts file and start writing some Kotlin in it, you will see your code being run on the fly presenting to you its result:

TDDish

You can even work test first if you need to figure out a quick algorithm and have your test run in every change you make!

I usually start with an assertThat function and a failing test and go from there:

Its a simple one but you get the point:

TIL: vararg in Kotlin is never nullable

Today I came across a piece of code that looked like this:

fun printAll(vararg names: String?) {
  names.forEach { name -> println(name) }
}

and noticed that the IDE did not complain about using names without checking if it is null names?.forEach { ... }!

After decompiling Kotlin’s bytecode I saw that no matter what type I use (String? or String) the java code was the same:

public static final void printAll(@NotNull String... languages) {
  //...
}

Does the Kotlin compiler ignore the nullable type completely? Turns out that yes!

And the reason is quite clear and straightforward but it hadn’t registered in my mind until now:

Note that vararg parameters are, as a rule, never nullable, because in Java there is no good way to distinguish between passing null as the entire vararg array versus passing null as a single element of a non-null vararg array.
kotlin’s forums

What if we pass a null value?

As a matter of fact if you pass a null value:

printAll(null)

the compiler makes sure that the java code will be called with a null value casted to the appropriate type:

printAll((String)null);

which ends up in an array of strings that has one element!

kscript from docker

This is one of those cases that you go down the rabbit hole and end up doing ten different things before the one that you initially wanted to!

My original intention was to try out kscript. What I ended up doing is learning about dockerfiles, building images and trying to run .kts files without having kscript, or kotlin, installed locally in my machine!

The result

A github repository that you can clone, run the install script and have a kscript executable that works as described here.

Why?

I wanted to play with kscript but did not want to install it on my machine. I don’t like bloating my OS by having libraries and software that might not be used often.

How?

Having everything installed in a docker image and use containers to play with kscript was a one way street for what I wanted to achieve.

Dockerfile

It was my first dockerfile but there are tons of tutorials that helped me out. I ended up using alpine, installing java through its repositories, sdkman using its installation guide and kotlin, kscript through sdkman!

Finally, kscript was added as the image’s entry point which means that every time a container is being run kscript will be the first command that gets executed.

And it worked for the most parts. By executing

docker run –rm -i kscript <params>
rm to remove the container after its done, -i to have the script’s output passed to the terminal

I was able to use kscript as described in its repository, except for the case of having a .kts file!

kscript-router.sh

For the case of a .kts file what turned out to solve my problem was to pass the file’s entire content. And this is part of what kscript-router.sh does. It checks if the first parameter is a .kts file and if so it passes its contents to the container. In every other case it passes all given parameters directly to the container.

install.sh

To tie everything together I added a script that creates the image, adds the router script to the user’s path and creates an alias, named kscript, for executing the router.

kscript-from-docker

Readable codebase: extract conditions / predicates

A quick way to make a codebase more readable is to extract long or complex conditions / predicates to their own functions. The function’s name will explain to the reader what is being checked allowing her to move forward instead of trying to figure out the context or the calculations that are taking place.

The task

	enum class Status {
	NotStarted,
	InProgress,
	Resolved,
	Cancelled
	}

	class Task(
	val id: Int,
	val description: String,
	val status: Status,
	val createdAt: LocalDateTime
	)

view raw extact-predicate-initial-code.kt hosted with ❤ by GitHub

Completed tasks of the last two days

Lets assume that we have a piece of code that prints all tasks that were created in the last two days and are, as the business experts calls them, completed. Which means that are either Resolved or Cancelled.

	val yesterdayAtStartOfDay = LocalDate.now().minusDays(1).atStartOfDay()
	val todayAtEndOfDay = LocalDate.now().atTime(23, 59)

	allTasks
	.filter { task ->
	(task.createdAt > yesterdayAtStartOfDay && task.createdAt < todayAtEndOfDay)
	&& (task.status == Resolved \|\| task.status == Cancelled)
	}
	.forEach { task -> println(task.description) }

view raw extract-predicate-initial-code-filter.kt hosted with ❤ by GitHub

We have two distinct concepts that can be extracted. One that will explain the date calculations and one that will force the business knowledge behind those two statuses.

createdInTheLastTwoDays()

The calculations can be extracted to a private function but since we are using Kotlin we will extract them to an extension function to make the code even more readable:

	allTasks
	.filter { task ->
	task.createdInTheLastTwoDays()
	&& (task.status == Resolved \|\| task.status == Cancelled)
	}
	.forEach { task -> println(task.description) }


	// extracted code:
	private fun Task.createdInTheLastTwoDays(): Boolean {
	val yesterdayAtStartOfDay = LocalDate.now().minusDays(1).atStartOfDay()
	val todayAtEndOfDay = LocalDate.now().atTime(23, 59)
	return this.createdAt > yesterdayAtStartOfDay && this.createdAt < todayAtEndOfDay
	}

view raw extract-predicate-created-at-extraction.kt hosted with ❤ by GitHub

isCompleted()

Another benefit of having “the mentality of extraction” (yep, I just made it up) is that eventually we will come across a case like the completed which is a business term that has not been transferred to the codebase!

So we don’t just make the code more readable but we improve our domain representation and force a rule that until now was known through documentations or, even worse, through conversations only.

	allTasks
	.filter { task -> task.createdInTheLastTwoDays() && task.isCompleted() }
	.forEach { task -> println(task.description) }

	//extracted code:
	class Task(
	val id: Int,
	val description: String,
	val status: Status,
	val createdAt: LocalDateTime
	) {

	fun isCompleted(): Boolean {
	return status == Resolved
	\|\| status == Cancelled
	}
	}

view raw extract-predicate-completed-extraction.kt hosted with ❤ by GitHub

The reader will not have to make any calculations while reading this code or trying to understand why only those statuses are being checked.

The code speaks for itself!

Null object pattern and sealed classes

In a recent code review one of my colleagues was concerned that part of the code I wrote might cause us problems because of the null object pattern I chose to use.

The code was something like this:

	class Task(
	val description: String,
	val assignedTo: AssignedTo
	)

	sealed class AssignedTo {
	object Nobody : AssignedTo()
	class User(val name: String) : AssignedTo()
	}

	fun main() {
	val buyMilk = Task("Buy milk", AssignedTo.Nobody)
	val writePost = Task("Write post", AssignedTo.User("le0nidas"))
	print(buyMilk, writePost)
	}

	private fun print(vararg tasks: Task) {
	tasks.forEach { task ->
	val user = when(task.assignedTo) {
	AssignedTo.Nobody -> "nobody"
	is AssignedTo.User -> task.assignedTo.name
	}
	println("Task '${task.description}' is assigned to $user")
	}
	}

view raw nullobjectpattern-start.kt hosted with ❤ by GitHub

and my colleague was referring to the Nobody usage.

That got me thinking. Can this usage of sealed classes be considered as an implementation of the null object pattern? Also, why is the usage of this design pattern a bad thing?

Null object pattern (wikipedia)

So, what is this pattern? This pattern is one way to solve the

we don’t want a method to return a null value and force ourselves to check it before usage
my definition 😛

Ok, it might be better to have an example:

Lets say that we have a service that returns the workout we did in a particular date. Each workout has the duration of the exercise and if we did not workout on the given date the service returns null (we’ll pretend for a moment that Kotlin does not have null safety or those great extensions like map, sum etc):

	abstract class Workout(val duration: Duration)

	class Walking(duration: Duration) : Workout(duration)
	class Swimming(duration: Duration) : Workout(duration)
	class Running(duration: Duration) : Workout(duration)

	fun workoutService(date: LocalDate): Workout? {

	val workouts = mapOf(
	LocalDate.of(2020, 4, 25) to Walking(Duration.ofHours(2)),
	LocalDate.of(2020, 4, 23) to Swimming(Duration.ofHours(1)),
	LocalDate.of(2020, 4, 22) to Running(Duration.ofMinutes(30))
	)
	return workouts[date]
	}

	fun main() {
	val days = listOf(
	LocalDate.of(2020, 4, 22), LocalDate.of(2020, 4, 23), LocalDate.of(2020, 4, 24), LocalDate.of(2020, 4, 25)
	)

	var sum: Long = 0
	for(day in days) {
	val workout = workoutService(day)
	if (workout == null) {
	continue
	}
	sum = sum + workout.duration.toMillis()
	}
	println("Total duration: ${Duration.ofMillis(sum)}") // Total duration: PT3H30M
	}

view raw nullobjectpattern-good-usage.kt hosted with ❤ by GitHub

By introducing a null object, for those days that we did not workout, we can remove the null checks and have a more readable code:

	abstract class Workout(val duration: Duration)

	class Walking(duration: Duration) : Workout(duration)
	class Swimming(duration: Duration) : Workout(duration)
	class Running(duration: Duration) : Workout(duration)
	// null object:
	object NoWorkout : Workout(Duration.ZERO)

	fun workoutService(date: LocalDate): Workout? {

	val workouts = mapOf(
	LocalDate.of(2020, 4, 25) to Walking(Duration.ofHours(2)),
	LocalDate.of(2020, 4, 23) to Swimming(Duration.ofHours(1)),
	LocalDate.of(2020, 4, 22) to Running(Duration.ofMinutes(30))
	)
	return workouts[date] ?: NoWorkout // usage of null object
	}

	fun main() {
	val days = listOf(
	LocalDate.of(2020, 4, 22), LocalDate.of(2020, 4, 23), LocalDate.of(2020, 4, 24), LocalDate.of(2020, 4, 25)
	)

	var sum: Long = 0
	for(day in days) {
	val workout = workoutService(day)
	sum = sum + workout!!.duration.toMillis() // yes, we are that!! sure
	}

	println("Total duration: ${Duration.ofMillis(sum)}") // Total duration: PT3H30M
	}

view raw nullobjectpattern-good-usage-2.kt hosted with ❤ by GitHub

Why is this a bad design?

From the example we could easily conclude that this pattern is quite helpful. Right?

Well, as everything in our industry: it depends! When we need a way to have some default values so that our calculations won’t crash and burn then it is a good choice. But if we use it in ways that we hide things we might end up in false successes.

For example, lets assume that we have a storage interface and a factory function that returns the proper storage implementation depending on a given value:

	interface Storage {
	fun save(workout: Workout)
	}

	class LocalStorage : Storage {
	override fun save(workout: Workout) {
	// it saves in our database
	}
	}

	class CloudStorage : Storage {
	override fun save(workout: Workout) {
	// it saves in someone else's database
	}
	}

	object NullStorage : Storage {
	override fun save(workout: Workout) {
	// it does nothing
	}
	}

	fun getStorage(type: String): Storage {
	return when (type) {
	"local" -> LocalStorage()
	"cloud " -> CloudStorage()
	else -> NullStorage
	}
	}

view raw nullobjectpattern-bad-usage.kt hosted with ❤ by GitHub

If something is not configured well we might end up using, through out our entire project, the NullStoragethinking that we have saved everything when in reality we lost our data!

In case you missed it there is a space in the cloud-type so no matter how many times we ask for the “cloud”-storage we will get the null-storage back. Silly example with a silly mistake but imagine what could go wrong in real projects!

So, back to the code that started all this

First thing is first:

Q: Is this usage of sealed classes an implementation of the null object pattern?

A: No. The Nobody object is just a representation of a valid state for the AssignedTo concept and does not provide any default values or hides any method usage.

Q: Can sealed classes be used for implementing the null object pattern?

A: Yes. Sealed classes can help us in having many values for one concept but the fact that we can use full fledged classes, that can also inherit a bunch of things, is quite powerful and can be easily misused. I don’t see anything stopping us from implementing the storage-example using sealed classes so we just need to think things carefully.

And now the twist:

As is, the code does not implement the design pattern but with a small change we can make it not only to implement it but to do it badly too! We’ll just move the name property to the parent and have Nobody provide an empty value:

	class Task(
	val description: String,
	val assignedTo: AssignedTo
	)

	sealed class AssignedTo(val name: String) {
	object Nobody : AssignedTo("")
	class User(name: String) : AssignedTo(name)
	}

	fun main() {
	val buyMilk = Task("Buy milk", AssignedTo.Nobody)
	val writePost = Task("Write post", AssignedTo.User("le0nidas"))
	print(buyMilk, writePost)
	// Task 'Buy milk' is assigned to
	// Task 'Write post' is assigned to le0nidas
	}

	private fun print(vararg tasks: Task) {
	tasks.forEach { task ->
	println("Task '${task.description}' is assigned to ${task.assignedTo.name}")
	}
	}

view raw nullobjectpattern-bad-usage-2.kt hosted with ❤ by GitHub

Q: Why is this bad? It does not hide anything, it provides a default value and to be honest we just need to pass “nobody”, instead of an empty string, to the super constructor.

A: Well, this time it depends on where we use the pattern and not how. If this code is part of our core layer then we are allowing this layer to decide on presentation issues! It should be the presentation layer that will check what value the assignedTo has and print “nobody”!

Our previous implementation of AssignedTo was forcing us to make the distinction between all of its values so we did not have much of a choice but to let the print function decide.

In conclusion

Think twice before using the null object pattern and, if you are in a team, try to put code reviews as part of your work flow. It is always good to have a fresh pair of eyes look at your code and even better to have a few people to discuss (and argue) about your choices.

Trying to explain something will make you understand it better!

A smooth refactor using sealed classes and a factory function

The problem

Lets say we have a contacts app and one of the screens shows the contact’s phone number.

	// domain:
	class PhoneNumber(val value: String)
	class Contact(val phoneNumber: PhoneNumber)

	// screen:
	class PhoneNumberScreen(
	private val phoneNumber: PhoneNumber
	) {

	fun render() {
	println("Phone number: ${phoneNumber.value}")
	}
	}

	// presentation layer:
	fun main() {
	val contact = Contact(PhoneNumber("12345"))
	show(contact.phoneNumber) // "Phone number: 12345"

	val contactWithInvalidPhoneNumber = Contact(PhoneNumber(""))
	show(contactWithInvalidPhoneNumber.phoneNumber) // "Phone number: "
	}

	private fun show(phoneNumber: PhoneNumber) {
	val phoneNumberScreen = PhoneNumberScreen(phoneNumber)
	phoneNumberScreen.render()
	}

view raw factory-function-the-problem.kt hosted with ❤ by GitHub

The problem with that code is that we can easily end up with instances that contain invalid state:

A phone number screen with an empty phone number!

Approach #1:

One way to prevent it is to add some logic in the presentation layer:

Open the phone number screen only if the phone number is not empty

	fun main() {
	val contact = Contact(PhoneNumber("12345"))
	show(contact.phoneNumber) // "Phone number: 12345"

	val contactWithInvalidPhoneNumber = Contact(PhoneNumber(""))
	show(contactWithInvalidPhoneNumber.phoneNumber) // does not show anything
	}

	private fun show(phoneNumber: PhoneNumber) {
	if (phoneNumber.value.isEmpty()) {
	return
	}

	val phoneNumberScreen = PhoneNumberScreen(phoneNumber)
	phoneNumberScreen.render()
	}

view raw factory-function-approach-1.kt hosted with ❤ by GitHub

Unfortunately this approach does not provide an actual solution but a patch. Our main goal is to have a PhoneNumberScreen that handles ONLY valid phone numbers.

Approach #2:

What we need is to move the necessary checks inside the PhoneNumberScreen class.

We could check the number’s validity on render and show some kind of message when there is no phone number.

	class PhoneNumberScreen(
	private val phoneNumber: PhoneNumber
	) {

	fun render() {
	if (phoneNumber.value.isNotEmpty()) {
	println("Phone number: ${phoneNumber.value}")
	} else {
	println("Invalid phone number")
	}
	}
	}

	fun main() {
	val contact = Contact(PhoneNumber("12345"))
	show(contact.phoneNumber) // "Phone number: 12345"

	val contactWithInvalidPhoneNumber = Contact(PhoneNumber(""))
	show(contactWithInvalidPhoneNumber.phoneNumber) // "Invalid phone number"
	}

	private fun show(phoneNumber: PhoneNumber) {
	val phoneNumberScreen = PhoneNumberScreen(phoneNumber)
	phoneNumberScreen.render()
	}

view raw factory-function-approach-2.kt hosted with ❤ by GitHub

It is quite clear that this solution provides a bad UX. Why open a screen when the user cannot use it? Also, in any additional usage of phoneNumber inside the PhoneNumberScreen we need to make the same check as in render() and handle both of its states.

Approach #3:

What we really need is to make sure that if the screen is created, then it is certain that it has a valid phone number. There are two ways to achieve that. The first one is by checking upon creation that the phone number is valid and throw an exception if it is not.

	class PhoneNumberScreen(
	private val phoneNumber: PhoneNumber
	) {

	init {
	require(phoneNumber.value.isNotEmpty()) { "cannot handle invalid phone number" }
	}

	fun render() {
	println("Phone number: ${phoneNumber.value}")
	}
	}

	fun main() {
	val contact = Contact(PhoneNumber("12345"))
	show(contact.phoneNumber) // "Phone number: 12345"

	val contactWithInvalidPhoneNumber = Contact(PhoneNumber(""))
	show(contactWithInvalidPhoneNumber.phoneNumber) // prints nothing
	}

	private fun show(phoneNumber: PhoneNumber) {
	try {
	val phoneNumberScreen = PhoneNumberScreen(phoneNumber)
	phoneNumberScreen.render()
	} catch (ex: IllegalArgumentException) {

	}
	}

view raw factory-function-approach-3.kt hosted with ❤ by GitHub

It works but we need to document it and add a try-catch wherever we create a screen instance.

The second one is by having a helper function that creates the screen only if the phone number is valid.

	class PhoneNumberScreen private constructor(
	private val phoneNumber: PhoneNumber
	) {
	fun render() {
	println("Phone number: ${phoneNumber.value}")
	}

	companion object {
	fun create(phoneNumber: PhoneNumber): PhoneNumberScreen? {
	return when {
	phoneNumber.value.isNotEmpty() -> PhoneNumberScreen(phoneNumber)
	else -> null
	}
	}
	}
	}

	fun main() {
	val contact = Contact(PhoneNumber("12345"))
	show(contact.phoneNumber) // "Phone number: 12345"

	val contactWithInvalidPhoneNumber = Contact(PhoneNumber(""))
	show(contactWithInvalidPhoneNumber.phoneNumber) // prints nothing
	}

	private fun show(phoneNumber: PhoneNumber) {
	val phoneNumberScreen = PhoneNumberScreen.create(phoneNumber)
	phoneNumberScreen?.render()
	}

view raw factory-function-approach-4.kt hosted with ❤ by GitHub

This also works as expected but once again we need to document it and on top of that handle any null values returned by the helper function.

Nevertheless this solution seems fine and for a very small code base is quite acceptable. The problem is that it does not scale alongside the code base. Imagine how many helper functions we need to implement every time we have to use a phone number instance in our components if we want to keep them “clean”.

The actual problem

The actual problem lies in the PhoneNumber itself. It represents more than one states and each time we use an instance of it we must “dive” in its value and translate it to that state.

What we really need is a better representation of a valid and invalid phone number.

Final approach

This is where we use sealed classes and separate the two states:

	sealed class PhoneNumber

	object InvalidPhoneNumber : PhoneNumber()

	data class ValidPhoneNumber(val value: String) : PhoneNumber() {
	init {
	require(value.isNotEmpty()) { "the number cannot be empty" }
	}
	}

view raw factory-function-final-approach-sealed-class.kt hosted with ❤ by GitHub

This way we accomplish our main goal: we change the PhoneNumberScreen to accept only instances of ValidPhoneNumber and can now be certain that the screen will be used only with valid data. The code is self documented and any further development in the screen class will not have to consider other states for the phone number:

	class PhoneNumberScreen(
	private val phoneNumber: ValidPhoneNumber
	) {
	fun render() {
	println("Phone number: ${phoneNumber.value}")
	}
	}

view raw factory-function-final-approach-screen.kt hosted with ❤ by GitHub

One big drawback of this change is that every usage of the PhoneNumber class has just broke (see: creation of Contact instances).

Fortunately there is a quick solution for that! Factory function:

A function that has the same name with the previously used class (PhoneNumber) and takes a single string parameter. If the parameter is not empty it returns a ValidPhoneNumber. In any other case it returns an InvalidPhoneNumber:

	fun PhoneNumber(value: String): PhoneNumber =
	when {
	value.isNotEmpty() -> ValidPhoneNumber(value)
	else -> InvalidPhoneNumber
	}

view raw factory-function-final-approach-factory-function.kt hosted with ❤ by GitHub

The end result is almost the same as the starting point but this time we have clear states and components that can guarantee that they will not crash because of erroneous data:

	fun main() {
	val contact = Contact(PhoneNumber("12345"))
	show(contact.phoneNumber) // "Phone number: 12345"

	val contactWithInvalidPhoneNumber = Contact(PhoneNumber(""))
	show(contactWithInvalidPhoneNumber.phoneNumber) // prints nothing
	}

	private fun show(phoneNumber: PhoneNumber) {
	if (phoneNumber is ValidPhoneNumber) {
	val phoneNumberScreen = PhoneNumberScreen(phoneNumber)
	phoneNumberScreen.render()
	}
	}

view raw factory-function-final-approach-main.kt hosted with ❤ by GitHub

Make your code reveal its usage

A small and simple example that shows one of the benefits of having domain objects.

Lets assume we need to make a request for some kind of a token and the flow for doing so goes like this:

Validate an email address
With the validated address validate a password
With both the validated values request for the token

The not so revealing way

	fun validateEmailAddress(value: String) {
	// does some validation
	}

	fun validatePassword(validEmailAddress: String, password: String) {
	// does some validation
	}

	fun requestToken(validEmailAddress: String, validPassword: String): String {
	return "some kind of token"
	}

view raw not-revealing-way.kt hosted with ❤ by GitHub

Q: Can the consumer of this API, without knowing the aforementioned flow, figure it out just by looking at the functions’ signatures?

A: I guess she could if the parameters’ names were like that. If not she needs to read the bodies of those functions to see that there is some kind of order that needs to be followed.

Q: Can the creator of this code be 100% certain that the functions will be used as expected and the passed parameters will be valid? For example, will requestToken always be called last and with valid addresses and passwords?

A: No! There is nothing that can guarantee that so, just to be safe, we check in every function that the provided values are valid and make the code flexible enough that, for example, each function could be used on its own. That will, potentially, lead to code duplication or unnecessary abstractions.

Q: What about errors and invalid values? Can the consumer of this API predict the code’s behavior on erroneous inputs without reading a documentation?

A: No. Just no.

The revealing way

First lets enrich our API with some, much needed, domain objects:

	sealed class EmailAddress
	data class ValidEmailAddress(val value: String) : EmailAddress()
	data class InvalidEmailAddress(val value: String, val error: String): EmailAddress()

	sealed class Password
	data class ValidPassword(val value: String) : Password()
	data class InvalidPassword(val value: String, val error: String): Password()

	data class Token(val value: String)

view raw revealing-way.kt hosted with ❤ by GitHub

Having those constructs we can change the functions and make them reveal both the order they can be used and their behavior:

	fun validateEmailAddress(value: String): EmailAddress {
	// does some validation and
	// if the validation fails it returns InvalidEmailAddress
	// otherwise a ValidEmailAddress
	}

	fun validatePassword(emailAddress: ValidEmailAddress, password: String): Password {
	// does some validation against the valid email address
	// if the validation fails it returns an InvalidPassword
	// otherwise a ValidPassword
	}

	fun requestToken(emailAddress: ValidEmailAddress, password: ValidPassword): Token {
	// having only valid values makes the code simple
	// just make the request and return the token
	return Token("some kind of token")
	}

view raw revealing-way-2.kt hosted with ❤ by GitHub

So lets pretend that we are the consumer of this API and all we have is the code.

Our main goal is to request for a token. By just looking at the functions’ signatures we see that there is a requestToken. Nice! Our task is half way done! What do we need for calling this function? A valid email address and a valid password. Ok. How do we get one of each?

Looking again at the signatures we see validateEmailAddress and validatePassword that return an EmailAddress and Password respectively. Lets check what those are. These are abstractions and each of them has been extended to a valid and an invalid state. The invalid one carries the error that occurred too! So, back to the functions.

We see that validating a password needs to be fed with a valid email address so we first need to call validateEmailAddress, then validatePassword and finally requestToken.

That’s it. We didn’t read the code of the functions and we didn’t have to worry about our inputs.