CleanKotlin

Follow The Recipe

2020-08-13T19:40:07+00:00

Birthday turtle

Today is your best friends birthday and she asked you to buy a turtle as a present. The problem is you have never seen a real turtle before. The only thing you know about turtles is that they can swim, have four legs and are reptiles. As you walk into the petstore you see a lot of different species of animals. You decide to write a simple program to determine whether an animal is a turtle or not.

The program you write looks something like this:

fun isTurtle() {
    var isTurle:Boolean = false
    if(canSwim()) {
        if(hasFourLegs()) {
            if(isReptile()) {
                isTurtle = true
            } else {
                isTurtle = false
            }
        } else {
            isTurtle = false
        }
    } else {
        isTurle = false
    }

    return isTurtle
}

Maintenance nightmare

After having checked all animals in the shop you are still left with two. They both can swim, have four legs and are reptiles.

You try to add one more condition, but because there are so many conditions already you find it hard to modify your program. You want to make sure you don’t make any mistake. The horror if your present happens to be a crocodile and the guests will be eaten instead of the cake.

How would you change the code to make this program more readable?

Refactor to a recipe

The first thing you realize is that when an animal cannot swim it cannot be a turtle. Therefore we can safely take out te canSwim() condition and use an early return when the animal cannot swim.

fun isTurtle() {

    // Check whether current animal can swim or not.
    if(!canSwim()) 
        return false // If the animal can't swim, we are done.

    // From now on we know that we are dealing with an animal that can swim

    var isTurle:Boolean = false

    // Therefore we don't have to check whether the turtle can swim anymore, so we remove the check.

    if(hasFourLegs()) {
        if(isReptile()) {
            isTurtle = true
        } else {
            isTurtle = false
        }
    } else {
        isTurtle = false
    }

    return isTurtle
}

After you have rewritten the checks on canSwim() it becomes clear you can do the same with the check on hasFourLegs() as well.

fun isTurtle() {

    if(!canSwim())
        return false

    if(!hasFourLegs())
        return false

    var isTurle:Boolean = false

    if(isReptile()) {
        isTurtle = true
    } else {
        isTurtle = false
    }

    return isTurtle
}

You already cleaned up your code a lot. Only the check on isReptile() is left.

fun isTurtle() {

    if(!canSwim())
        return false

    if(!hasFourLegs())
        return false

    if(!isReptile())
        return false
    
    // When this part is reached, we know our animal can swim, has four legs and is a reptile and therefore (probably) is a turtle.

    return true
}

Adding new requirements

Finally to distinguish the turtle from the crocodile you come up with one final check. Does the animal have a shell? Now that you have written your code like a recipe it becomes trivial for you to add this new condition. A recipe can easily be read from top to bottom.

fun isTurtle() {

    if(!canSwim())
        return false

    if(!hasFourLegs())
        return false

    if(!isReptile())
        return false

    // Distinguish between turtles en crocodiles
    if(!hasShell())
        return false

    return true
}

Now you know the basics of rewriting a nested solution to a recipe. In this particular case there is an even more clean solution.

fun isTurtle() {
    return canSwim() && hasFourLegs() && isReptile() && hasShell()
}

But, aren’t early returns a bad thing?

Some would argue that early returns make your code harder to understand because there are multiple places where you method could end. In my experience this is never a problem until your methods become very long and complex. When this happens you should probably deal with those long methods instead i.e. by reducing their length and complexity first.

The Recipe

The general recipe is as follows:

Try to do X
If X didn’t work -> stop
continue with the assumption that X worked

In the following example you can see this pattern at work. The fridge in this example is a simple state machine and all illegal transitions will throw an exception.

You can try this code out by copying it to the kotlin playground

fun main() {
    val fridge = Fridge()
    fridge.open()
    fridge.putElephantInFridge()
    fridge.close()

    fridge.open()
    fridge.takeElephantFromFridge()
    fridge.close()
}

class Fridge {

    var isOpen: Boolean = false
    var isEmpty: Boolean = true

    fun open() {
        if(isOpen)
            throw IllegalStateException("Unable to open an already opened fridge")

        isOpen = true
        println("Fridge opened")
    }

    fun close() {
        if(!isOpen)
            throw IllegalStateException("Unable to close an already closed fridge")

        isOpen = false
        println("Fridge closed")
    }

    fun putElephantInFridge() {
        if(!isOpen)
            throw IllegalStateException("Unable to put elephant in a closed fridge")

        if(!isEmpty)
            throw IllegalStateException("Unable to put elephant in fridge because there is no room left")

        isEmpty = false
        println("Elephant put in fridge")
    }

    fun takeElephantFromFridge() {
        if(!isOpen)
            throw IllegalStateException("Unable to take an elephant from a close fridge")

        if(isEmpty)
            throw IllegalStateException("There is no elephant to take out of the fridge")

        isEmpty = true
        println("Elephant taken from fridge")
    }
}

Assertions

To Clean up this code even further, you can use Kotlins require(value:Boolean) and check(value:Boolen) methods. These methods assert that a certain condition has been met and throw an IllegalArgumentException or IllegalStateException when it hasn’t been. Let’s see how our fridge looks like with the right checks. Notice that the condition has been negated and only throws an exception when the condition is false.

fun main() {
    val fridge = Fridge()
    fridge.open()
    fridge.putElephantInFridge()
    fridge.close()

    fridge.open()
    fridge.takeElephantFromFridge()
    fridge.close()
}

class Fridge {

    var isOpen: Boolean = false
    var isEmpty: Boolean = true

    fun open() {
        check(!isOpen) { "Unable to open an already opened fridge" }

        isOpen = true
        println("Fridge opened")
    }

    fun close() {
        check(isOpen) { "Unable to close an already closed fridge" }

        isOpen = false
        println("Fridge closed")
    }

    fun putElephantInFridge() {
        check(isOpen) { "Unable to put elephant in a closed fridge" }

        check(isEmpty) { "Unable to put elephant in fridge because there is no room left" }

        isEmpty = false
        println("Elephant put in fridge")
    }

    fun takeElephantFromFridge() {
        check(isOpen) { "Unable to take an elephant from a close fridge" }

        check(!isEmpty) { "There is no elephant to take out of the fridge" }

        isEmpty = true
        println("Elephant taken from fridge")
    }
}

Today you learned how to write software like you write a recipe. I hope it tastes good.

Lightbulbs

2020-08-13T19:40:07+00:00

Lightbulbs

When we press the button the light turns on.

fun main() {
    pressButton()
}

fun pressButton() {
    println("Button Pressed")
    turnOnLight()
}

fun turnOnLight() {
    println("Light turned on")
}

When we press the button again the light turns off.

var lightOn: Boolean = false

fun main() {
    pressButton()
    pressButton()
}

fun pressButton() {
    println("Button Pressed")
    if(lightOn)
        turnLightOff()
    else
        turnLightOn()
}

fun turnLightOn() {
    lightOn = true
    println("Light turned on")
}

fun turnLightOff() {
    lightOn = false
    println("Light turned off")
}

More requirements

The only constant in software development is Change and to rub it in our face, Your Manager comes in with a new set of requirements.

Instead of 1 button, I want multiple buttons. These buttons could toggle the same light on or off or they could toggle a different light. A button only changes the state of a single lightbulb.

Our model can’t handle these changes :O

These new requirements cause a lot of problems for or existing code. We made the assumption that there will only ever be one button and only one Light. Just adding new methods and adding more state won’t solve our problem, because it will make our code very complex very fast.

Refactor first then add the new features.

Refactoring is the art of changing the way your code is organized without changing it’s behaviour. In the past I did make the mistake of refactoring and incorporating new features at the same time.

val light = Light()

fun main() {
    pressButton()
    pressButton()
}

fun pressButton() {
    println("Button Pressed")
    if(light.on)
        light.turnOff()
    else
        light.turnOn()
}

class Light {
    var on:Boolean = false
    fun turnOn() { 
        check(!on) { "Light is already on!" }
        on = true
        println("Light turned on")
    }

    fun turnOff() {
        check(on) { "Light is already off!" }
        on = false
        println("Light turned off")
    }
}

When we run our code. It should behace exactly the same as before.

Now let’s extract our button to it’s own model as well.

fun main() {
    val light = Light()
    val button = Button(light)

    button.press()
    button.press()
}

// A button operates on a light, so it needs a reference to the light.
class Button(val light:Light) {
    fun press() {
        println("Button Pressed")
        if(light.on)
            light.turnOff()
        else
            light.turnOn()
    }
}

class Light {
    var on:Boolean = false
    fun turnOn() { 
        check(!on) { "Light is already on!" }
        on = true
        println("Light turned on")
    }

    fun turnOff() {
        check(on) { "Light is already off!" }
        on = false
        println("Light turned off")
    }
}

Code Smell

Currenntly our button is responsible for turning the light on and off. The Button first asks a question to the light: Are you on or off? Depending on the lights answer the button will tell the light to witch state to switch. If the button makes a mistake, the light will throw an exception and tell the button It can’t do as requested.

When your code is asking a lot of questions to make a decision This can be an indicator of a design problem.

What would you change to make the interaction between the button and the light simpeler?

Classes are both data and behaviour

Data and behaviour that acts upon that data are closely coupled and should reside close together.

By making the light responsible for and its state transitions we get a Light that is better.

fun main() {
    val light = Light()
    val button = Button(light)

    button.press()
    button.press()
}

// A button operates on a light, so it needs a reference to the light.
class Button(val light:Light) {
    fun press() {
        println("Button Pressed")
        light.toggle()
    }
}

class Light {
    var on:Boolean = false

    fun toggle() {
        if(on)
            turnOff()
        else
            turnOn()
    }

    private fun turnOn() { 
        check(!on) { "Light is already on!" }
        on = true
        println("Light turned on")
    }

    private fun turnOff() {
        check(on) { "Light is already off!" }
        on = false
        println("Light turned off")
    }
}

Because we don’t want turnOn() and turnOff() be directly available as methods on our light anymore, we can make them private. We can also reduce the complexity of the toggle() method and removing the turnOn() and turnOff() methods completely. If in the future there is a need to reintroduce these methods you can write them again, but for now they only add unnecessary complexity. If you are scared to throw code away remember that you always have version control. Also see YAGNI.

fun main() {
    val light = Light()
    val button = Button(light)

    button.press()
    button.press()
}

// A button operates on a light, so it needs a reference to the light.
class Button(val light:Light) {
    fun press() {
        println("Button Pressed")
        light.toggle()
    }
}

class Light {
    var on:Boolean = false

    fun toggle() {
        if(on)
            println("Light turned off")
        else
            println("Light turned on")

        on = !on
    }
}

Double negatives should not not be avoided

2020-08-08T20:47:23+00:00

Booleans are the bread and butter of decision making in most modern programming languages and in Kotlin this is no exception. I will discuss with you some ways to clean up your boolean logic and you will explore some best practices in giving good positive names to our binary friends.

Double negations are not not bad.

You should not use double negations in your code because they are hard to read and understand. They also significantly increase the amount of bugs and errors that can hide in your program. I invite you to try the following exercise to better understand why Double negatives form a problem.

Which numbers will be printed to the console?

val isNotTyping = false
val isTyping = true

fun main() {
    doubleNegation()
    singleNegation()
    noNegation()
}

fun doubleNegation() {
  if(!isNotTyping)
    println(1)
  else
    println(2)
}

fun singleNegation() {
  if(isNotTyping)
    println(3)
  else
    println(4)
}

fun noNegation() {
  if(isTyping)
    println(5)
  else
    println(6)
}

Most programmers take longer and make more mistakes interpreting the code that uses double negations compared to the code where less negations are used. This is why you should always try to write boolean variables and parameters in their positive form.

Here is the solution. Did you get it right?

1
4
5

Parameters and variables are not the only places where problematic usage of double negations can be found. Methods, that have a boolean as return type, suffer from the same problems.

fun isNotOdd(value:Int):Boolean {
  // Implementation
}

Will be less clear and should be replaced with:

fun isEven(value:Int):Boolean {
  // Implementation
}

Try to start positive

If you really need the negative form of a method consider providing the positive part first and let the negative form call the positive form. Most of the time it is easier to implement the positive form anyway. Letting the negative form call the positive form has the added benefit of avoiding duplication, which limits the amount of code that has to be touched when requirements change.

fun isNotDone():Boolean = !isDone()

fun isDone():Boolean = progress == 100

Clean up existing code

Often you have to deal with code that has already been written by you or an other person. As per the Boy Scout Rule we should Leave our code better than we found it.

Let’s say you found this piece of code that deals with boxes containing integers.

Which steps would you take to improve this code?

You can use the Kotlin Playground to test the code in your browser.

fun main() {
    Box(7).print()
    Box(null).print()
}

private fun Box.print() {
    if(!isNotEmpty())
    	println("box is empty")
    else
    	println("box contains: ${value}")
}

class Box(val value:Int?) {
    fun isNotEmpty() = value != null
}

Make sure you check if your code still compiles and behaves the same way after each step.

Step 1: Introduce positive form.

fun main() {
    Box(7).print()
    Box(null).print()
}

private fun Box.print() {
    if(!isNotEmpty())
    	println("box is empty")
    else
    	println("box contains: ${value}")
}

class Box(val value:Int?) {
    fun isNotEmpty() = value != null
    fun isEmpty() = !isNotEmpty() // Introduce positive form which calls the other form.
}

Step 2: Replace each double negative with a call to the new function.

fun main() {
    Box(7).print()
    Box(null).print()
}

private fun Box.print() {
    if(isEmpty()) //Replace all double negatives
    	println("box is empty")
    else
    	println("box contains: ${value}")
}

class Box(val value:Int?) {
    fun isNotEmpty() = value != null
    fun isEmpty() = !isNotEmpty()
}

Step 3: If negative form is only used in the positive form use the Inline Function Refactor method to move to merge the body of the negative form (isNotEmpty()) to the positive form (isEmpty()).

fun main() {
    Box(7).print()
    Box(null).print()
}

private fun Box.print() {
    if(isEmpty())
    	println("box is empty")
    else
    	println("box contains: ${value}")
}

class Box(val value:Int?) {
    //Remove unused isNotEmpty() method. If you still need it make sure it calls isEmpty()
    fun isEmpty() = !(value != null) // replace method call by implementation.
}

Step 4: Clean up the positive form a little further

fun main() {
    Box(7).print()
    Box(null).print()
}

private fun Box.print() {
    if(isEmpty())
    	println("box is empty")
    else
    	println("box contains: ${value}")
}

class Box(val value:Int?) {
    fun isEmpty() = value == null // making method implementation more expressive
}

Instead of using a method named isNotEmpty to see whether a box is full it would probably make more sense to introduce a method called isFull. Often you have to search a little longer for names that better convey the right meaning.

fun main() {
    Box(7).print()
    Box(null).print()
}

private fun Box.print() {
    if(isFull()) //Replaced isEmpty() with isFull()
    	println("box contains: ${value}") // Swap
    else
    	println("box is empty") // Swap
}

class Box(val value:Int?) {
    fun isFull() = !isEmpty() // Introduced new method in its positive form
    fun isEmpty() = value == null
}

There’s no reason to use complex and confusing double negatives in your code. So do us all a favor. Don’t not avoid double negations.