Forem: Sinuhe Jaime

The beauty of currying

Sinuhe Jaime — Wed, 08 Jun 2022 22:52:18 +0000

What is currying?

Currying is the fine art of transforming a function with arity n into n functions with arity 1.

This means: Given a function that takes X parameters, generate X functions that take only 1 parameter.

Using the wikipedia example:

Given x = ƒ(a, b, c) it becomes:
- h = g(a)
- i = h(b)
- x = i(c)
Or in a single sequence call: x = g(a)(b)(c)

The name comes from Haskell Curry, a famous mathematician who developed a lot of concepts in modern math.

What it means in modern programming?

It simply means that you have a way to reduce the complexity of a function call creating intermediate functions which in turn return newer functions.
It will be more clear with examples...

A taste of currying

Let's start with a "simple function" it takes 2 numbers and returns the sum of them:

sum = { a: Int, b: Int } => a + b

Let's imagine for a second that we have a curry function that will give back the curried version of our function, a call of: curry(sum) will generate curriedSum which can be invoked like: curriedSum(a)(b) instead of the original call: sum(a, b).

There's also the possibility of actually set some of its values and do PARTIAL APPLICATION which means setting a value for one (or more) of the parameters.

On our sum example:

val curriedSum = curry(sum) // return value is: { a -> { b -> a + b } }
// Or also expressed as: (Int) -> (Int) -> Int
val add5 = curriedSum(5) // returns: (Int) -> Int = { b -> 5 + b } 
val add7 = curriedSum(7) // returns: (Int) -> Int = { b -> 7 + b } 

add5(42) // 47
add7(13) // 20
add5(add7(10))
curriedSum(17)(7)// 24 :: add5(add7(10)) -> add5(17)

Why would I want that?

There are multiple reasons for wanting to curry a function:

We don't have all the values that will be passed right now, we usually have to create callbacks or proxies or mechanism to obtain these values before actually calling a function.
We need to pass a function as parameter to another function (callbacks) and we already have a function defined to do the work.
We want to partially apply a function to pass it along to other places but keeping our data contextualized in there, sounds weird but imagine you have to pass a callback or pass a filtering function, and you already have a function that does the job, but with additional flags or parameters.
We need a simple way to provide a complex API shared between parts at different moments.

Truth is you maybe don't need it or have other approaches that can do the work as well, still is worth the shot to understand how it works in case you need it some day.

Let's see it in action

For this example, let's imagine we have a function that can do a POST to a web service and returns information.

fun <T> postCall(
    domain: String, 
    port: Int, 
    path: String, 
    queryParams: QueryParams,
): T {
    //... Here happens the magic call
}

Each call will be complex:

postCall<MovieResponse>(
  "moviedb.com", 
  8090, 
  "/movies/scott-pilgrim", 
  QueryParams(
    "order" to "asc",
    "type" to Types.JSON,
    "comments" to false
  )
)
//...
postCall<MovieResponse>(
  "moviedb.com", 
  8090,
  "/movies/lego-movie", 
  QueryParams(
    "order" to "desc",
    "type" to Types.JSON,
    "comments" to true
  )
)
//...

This is error-prone and can be improved:

Using a builder:

  createMovieCall()
    .forMovie("lego-movie")
    .withParams("order" to "desc", "type" to Types.JSON, "comments" to true)
    .call()

Using a class:

    val imdbService = MovieService(
        params = "default", 
        domain = Domains.IMDB
    )
    imdbService.getMovie("scott-pilgrim")

Other cooler ways that are not as cool as currying.

But with currying we can do something like:

val movieService = curry(postCall)("moviedb.com")(8090)

val scottPilgrimCall = movieService("/movies/scott-pilgrim")
val scottPilgrimWithComments = scottPilgrimCall("comments" to true)
val scottPilgrimNoComments = scottPilgrimCall("comments" to false)

val legoMovieCall = movieService("/movies/lego-movie")
val legoMovieYAML = legoMovieCall("type" to Types.YAML)
val legoMovieXML = legoMovieCall("type" to Types.XML )
val legoMovieJSON = legoMovieCall("type" to Types.JSON)

This approach allow to create the intermediate calls and keep previous parameters without problems, we can even create a
"movie service generator":

fun movieServiceGenerator(
  movieWeb: string
): (String) -> (QueryParams) -> MovieResponse =
  curry(postCall)(movieWeb)(8090) // Assuming both sites use this port

val imdbService = movieServiceGenerator("imdb.com")
val cuevanaService = movieServiceGenerator("cuevana3.me")

// And the calls will be similar:

val jumanjiIMDB = imdbService("/movie/jumanji")(QueryParams())
val jumanjiCuevana = cuevanaService("/92345/jumanji")(QueryParams("server" to "webfree2"))

The syntax is different but the way we pass data evolves to return functions with partially applied data so, we can build functions with simpler calls.

How to implement it

Depending on what your language allows with functions it can be easy or hard or even unreadable (but easy to use).

For example, in Haskell all calls with multiple parameters are auto curried which means that a function:

postcall :: String -> Int -> String -> [(String, String)] -> a

Is the same as:

postcall :: String -> (Int -> (String -> ([(String, String)] -> a)))

So we can do partial application if needed:

imdbservice = postcall "imdb.com" 8090

scott_pilgrim = imdbservice "/movies/scott-pilgrim"
scott_pilgrim_comments = scott_pilgrim [("comments", "true")]

In JS defining a currying function gets interesting:

function curry(func) {
    return function curried(...args) {
        if (args.length >= func.length) {
            return func.apply(this, args)
        } else {
            return function (...args2) {
                return curried.apply(this, args.concat(args2))
            }
        }
    }
}

But there are a lot of solutions out there, like lodash:

const curried = _.curry(postcall)
const imdbService = curried("imdb.com")(8090)
const legoMovie = imdbService("/movies/lego-movie")({})

Other languages can get complicated as we need to know the number of arguments for our application, like kotlin:

fun <A, B, R> curry(f: (A, B) -> R): (A) -> (B) -> R {
    return { a: A -> { b: B -> f(a, b) } }
}

fun <A, B, C, D, R> curry(f: (A, B, C, D) -> R): (A) -> (B) -> (C) -> (D) -> R =
    { a: A ->
        { b: B ->
            { c: C ->
                { d: D -> f(a, b, c, d) }
            }
        }
    }

fun postCall(
  web: String, 
  port: Int, 
  path: String, 
  params: Map<String, String>): MovieResponse {
    //...
}

val curried = curry(::postCall)
println(curried("imdb")(9090)("/lego")(mapOf("format" to "json")))
// And so on...

Depending on how much your platform (language) allows, it can be messy...


@FunctionalInterface
interface TetraFunction<A, B, C, D, R> {
    R apply(A a, B b, C c, D d);
}

class Curry {
    public static <A, B, R> Function<A, Function<B, R>> curry(BiFunction<A, B, R> f) {
        return (a) -> (b) -> f.apply(a, b);
    }

    public static <A, B, C, D, R> 
    Function<A, 
            Function<B, 
                    Function<C, 
                            Function<D, R>>>> curry(TetraFunction<A, B, C, D, R> f) {
        return (a) -> (b) -> (c) -> (d) -> f.apply(a, b, c, d);
    }
}

//Usage:
class Example {
    static <T> T postCall(
            String movieWeb, 
            int port, 
            String path, 
            Map<String, String> params) {

    }

    public static void main(String[] args){
        Function<String, 
                Function<Integer, 
                        Function<String, 
                                Function<Map<String, String>, 
                                        MovieResponse>>>> curriedPostCall = Curry.curry(Example::postCall);

        MovieResponse movieResponse = curriedPostCall.apply("imdb.com").apply(9890).apply("/lego-movie").apply(new HashMap());
    }
}

The concept and application stays almost the same, only adapting it to each language/platform.

And I did not show this time a complete example as we already covered a lot, but the ideal scenario for using currying is when you have functions taking functions and returning other functions.

Conclusions

Functional Programming creates a lot of intermediate data
Currying is cool if you need to simplify your function calls
Currying is cool if you need to partially apply your functions
Currying is not a silver bullet but can help you create a simpler API

Let's talk DSL with Kotlin

Sinuhe Jaime — Mon, 17 Feb 2020 04:28:40 +0000

What is a DSL

A DSL is one way to wrap common operations that you do or a group of people do frequently.

For example you go every day for coffee and you order the same (double espresso with ice in my case), this means you have this common operation that your barista and you already know. So eventually instead of going explicitly saying: "Hey Jhoon, give me double espresso with ice" you simply say: "Hey Jhoon, I'll take the usual". Jhoon and you already know that the usual is a double espresso with ice so you can skip some details and make it easy for both of you to order.

Another example is ordering sandwiches in Mexico, instead of asking for: "One with ham, cheese and sausage" you just ask for a "Spanish sandwich". Yes, probably the first time you see this it will seem weird to you, but the thing is that is a simpler way for the sandwich place to know what you want to order. They already have a whole menu based on countries and what ingredients they contain. But maybe you want your sandwich without onions, that's fair some people don't like onions (I personally love them) so you will say: "A Spanish sandwich without Onions". This means that even when the recipe is already defined you can customize part of it.

A DSL is just that, some local way to define (or execute) something. In our examples, a meal order. In other cases is a configuration, a build definition, a way to create a JSON, a network call, an asynchronous job, etc.

DSL makes easier define common operations or complex operations using a locally defined language… actually… DSL means that: Domain-Specific Language. So… requesting food to your sandwiches place? That's Domain-Specific! as the names only apply to sandwiches places, if you order the same at a pasta restaurant they probably don't get it.

DSL to the rescue

When you are developing something you eventually start repeating things: need a thumbnail for that article? Create a network call pointing to the image, need to build data for a login request? Build a JSON and pass it to the network call, defining an alert to the user? build the dialog with a builder…

And these aren't the only cases, you probably already abstracted the way to achieve this kind of operations: with a function, with some design patterns that make easier the task, with a class wrapping most of the process/logic, etc.

But a DSL goes even further: it adds a quicker way to complete tasks/achieve something in your project without having to worry about the implementation details. This means a coworker, a friend or some contributor to your project could easily start adding functionality using your DSL without knowing what's happening internally. Also if you later decide to change the HTTP library for something lightweight or change the JSON parser or some part of your software needs improvement but you don't want to mess with all the usages, you can change internally how your DSL achieve things and keep the DSL the same, so fixing and improving won't affect how others achieve things with the DSL.

Common use case for DSL

We use some DSL frequently without noticing: RegExp (Regular Expressions), AWK, SQL, CSS, SASS, XML, etc. They are considered DSL as they apply to an specific kind of task. For example, you cannot use a RegExp to open a file or to perform a network call, these aren't things RegExp can do, it's main purpose is to search and process text. As well as you cannot use CSS to process an audio file and add new sounds to it. These examples work on specific, limited, and detailed areas and they work quite well defining a simpler way to achieve their purpose than programming all the logic by ourselves.

You can create a DSL for your project defining a group of functions, data types, classes and resources. They need to provide a way to make some tedious task easier and should be a simpler way to read through code.

Some languages provide easy ways to create DSLs and provide with tools to validate and help your DSLs work properly.

If you're a reading this, I hope you are familiar with Kotlin and you want to take your coding to the next level: write less and do more. Well, let's see how Kotlin helps us building DSLs and validating the information within.

Let's see some examples

As mentioned before, we can define a DSL for common tasks, let's take the previously mentioned ideas:

Create a network call pointing to the image

fetchImage {
    src = "https://via.placeholder.com/350x150"

    onDone { img ->
        myThumbnail.image = img
    }

    default = resources.default_thumbnail
}

Build a JSON for that login

val loginInfoJson: Json = buildJson {
    property(key = "username") {
        value = "Sierisimo"
    }

    property {
        key = "password"
        value = "supersecret"
    }

    property {
        key = "meta"
        value = buildJson {
            property(key = "service") {
                value = "google"
            }

            property(key = "token") {
                value = store.token
            }
        }
    }

    property(key = "emails"){
        value = arrayOf("sierisimo@mail.com", "notmyrealemail@placeholder.com")
    }

    minified = true
}

Show a message to the user

showMessage {
    title = "Hey friend!"
    message = "We notice you are working too hard and we are proud of you. Take five minutes back and relax, you deserve it!"

    confirmButton {
        text = "You're right!"
        onClick { dialog ->
            dialog.dismiss()
        }
    }

    cancelButton {
        text = "No, let's keep the hard work"
        onClick { dialog ->
            dialog.dismiss()
        }
    }
}

These examples are just hypothetical and can change for your needs… and that's another awesome part of a DSL: it will adapt to your needs! As you'll build it for solving your Domain problems.

Ok, you got me. Show me how

First thing you should do is find a common thing you do in your code. Something that you already notice you repeat like launching something, opening something, making a request, building something complex, etc.

For example, Kotlin Standard Library already includes a minimal DSL for building a String, it makes easy to create a single StringBuilder and add things to it using a lambda function. It also adds functions to have a vararg arguments instead of individual calls.

val text = buildString {
    append("Hi", "my", "friend")

    append("more text")
}
//text: Himyfriendmore text

There's an official DSL library for building HTML with kotlin, you can check it here. A short example is shown below:

createHTML().html {
    body {
        div {
            a("https://dev.to") {
                +"Main site"
            }
        }
    }
}

This will generate the next html:

<html>
  <body>
    <div><a href="https://dev.to">Main site</a></div>
  </body>
</html>

Let's create a DSL for creating JSON objects.

Our first approach

We already defined how our DSL will work a few lines above. We know the first thing we will need is a function that will create a Json but also that it will return a Json type. Let's define both:

class Json

fun buildJson(): Json {
    return Json()
}

Additionally we would like to take use buildJson { … } which is actually a call to a function passing a lambda as parameter. Inside that lambda we will invoke multiple functions to add properties to the Json and to modify/add values. This will require that all operation are referring to the final Json object that will be generated. We can achieve this using a lambda with receiver:

fun buildJson(buildBlock: Json.() -> Unit): Json {
    val json = Json()
    json.apply(buildBlock)
    return json
}

This tells us that now we have to pass a lambda to the function in order to build the Json and also this lambda will have access to the information of the Json. In some cases you want to create an intermediate class to remove the mutability of the final object… but we will discuss that approach on a later article.

Now we have the beginning of our DSL.

Adding inner functions

For every property on our final Json we want to allow a call on our DSL to something like: addProperty or just property to make it more readable, as our function is buildJson the property function can be understood as adding a new property more than querying.

To make this possible we can create individual functions or simply add them as methods to the Json class:

class Json {
    fun property(
        key: String,
        value: Any? = null
    ){
        //Logic to add a property will live here
    }
}

This new method inside of the Json class allows our DSL to behave in this way:

buildJson {
    property(key = "name", value = "Sinuhe")
}

But this is limited as we cannot do many computations or things in an expressive way. Our DSL should allow the properties to be "dynamic" in a way they are actually calculated. Once again we go with a lambda with receiver:

class Json {
    fun property(
        key: String = "",
        value: Any? = null,
        propBlock: JsonProperty.() -> Unit = { }
    ) {
        val jsonProperty = JsonProperty(key, value)
        jsonProperty.apply(propBlock)
        //More logic here for registering the property somewhere
    }
}

data class JsonProperty(
    var key: String,
    var value: Any?
)

As you can notice (and not mentioned before), we are adding default values, this means that invocations of our DSL can skip some values in order to let the DSL take the decision for trivial values or implementations:

//Example 1
buildJson {
    property(key = "name", value = "Sinuhe")

    //Also valid:
    property(key = "") {
        value = 0
    }

    property {
        key = "pwd"
        value = "Some Complicated password"
    }
}

DSL Should be safer

So far our final Json doesn't actually hold or contains any information. We should add some properties to it on each invoke of property to keep track of these values:

class Json {
    private val properties: MutableMap<String, Any?> = mutableMapOf()

    val keys: Set<String>
        get() = properties.keys

    fun property(
            key: String = "",
            value: Any? = null,
            propBlock: JsonProperty.() -> Unit = {}
    ) {
        val jsonProperty = JsonProperty(key, value)
        jsonProperty.apply(propBlock)

        properties[jsonProperty.key] = jsonProperty.value
    }
}

But now we have something not so cool on our DSL, the DSL can be used like this:

buildJson {
    property(key = "name") {
        value = "Sinuhe"

        println(keys)
    }
}

This is a mistake as we don't expect to have access to keys which is a property of Json inside of the property block. This is less readable as we (the owners of the DSL) are aware that keys belongs to the top block but the users (maybe us in 2 months or maybe our coworkers or someone using our public library) won't be aware of why keys exists here "why a property has keys?.

To avoid this type of errors, Kotlin provides us with a simple way to let the compiler check if something is available or accessible in a block. We first need to create an annotation marked with @DslMarker:

@DslMarker
annotation class JsonDSL

To let the Kotlin compiler to check usages of our DSL we need to mark the types (classes and interfaces) involved on our DSL. This check will validate that all lambdas with receiver limit their access to just the receiver, the rule in case of two or more receiver are involved or even a lambda without receiver is present is that "the top closest one wins" this means the type closest in a top level function allows the access on it's fields to the block. In that way we can hide fields and other functions from inner blocks, this will happen at compile time, making the usages safer.

@DslMarker
annotation class JsonDSL

@JsonDSL
data class JsonProperty(…)

@JsonDSL
class Json {
    …
}

What's next

From here we can extend our DSL for other operations, common suggestions are to override operators, add extension functions inside of our class, add get/set functions for accessing, etc. to make the DSL even more cool:

class Json {
    infix fun String.toValue(value: Any?) {
        properties[this] = value
    }
}

//On the DSL:

buildJson {
    "lastName" toValue 5

    "innerJson" toValue buildJson {

    }
}

Conclusions

There's no specific rules for how to build a DSL or what elements to add. As a DSL is for specific operations or rules on a certain domain (as the name says), some rules or naming conventions can differ.

Also notice that designing and building a DSL takes some time so it's a solution in the long term that will make writing code easier for you and the projects using it. The final user of your application/service/software probably won't notice the presence of a DSL but developers will (unless you are writing a library/framework in which case your final users are developers).

There's out there some DSL already built with these techniques that you can check an take inspiration from:

Anko (Deprecated but still something good to read)
Kotlinx.HTML
KTON
Skrape.it
Others not mentioned (but if you give me the links I'll include them)

/////////////////////////////////////

Reach me with questions, comments or just to show off your DSLs at @sierisimo in both Github and Twitter.

The Function that changed my mind

Sinuhe Jaime — Tue, 17 Sep 2019 15:49:37 +0000

When writing code, we should always have a place for improvement. Improvement can present itself in different ways. A proof of it, is the attention to CI (Continuous Integration) and CD (Continuous Delivery) has significantly grown in recent years. Same goes for new languages and technologies.

Nevertheless, this doesn't involve changing to a new language, technology, nor tool. Some of these improvements are so simple as changing how something works, i.e. adding tests/abstractions, changing patterns, etc. This is how I have proceeded in several projects I have worked in.

Disclaimer: Whether you have talked with me in person, or have attended to one of my talks at meetups, it's likely, you already have heard me talking about it, even on YouTube with the GDG Santo Domingo (in spanish) or Kotlin/Everywhere Guadalajara and Mexico City.

Another disclaimer: This article is not about architecture –even though it's a hot topic in the Android community –, best practices or even about how to organize an Android Application. It's just about a set of changes that showed me some Kotlin concepts. Also, I started to implement this aforementioned strategies almost 3 years ago, therefor by the time this article is published, the libraries from Google –like core-ktx– will probably being updated or improved. And just to be clear: It's good to mention that the approaches mentioned in the following lines don't apply to all scenarios nor cases; the solutions mentioned in this article depend on scenarios or needs themselves, besides individual reasons to choose them over the others.

But first… some Context

If you're an Android Developer or have worked with Android, you probably caught the pun intended by this title. If not, let me explain it to you quickly.

In Android development, everything happening on your application has a Context and to make some stuff work, you need to deal with a Context as well. This is no more than a class that Android uses to provide information and access to the app.

One specific case arises at the time it's required to start a new Activity on your app. This means -succinctly- launching a whole new screen or an external application. In order to accomplish it, firstly you should create an Intent based on your Context and pass the Activity you would like to launch:

val myIntent = Intent(context, MyNextActivity::class.java)

Then you can start MyNextActivity from another Activity simply using this intent: startActivity(myIntent)

If your application relies on activities for showing varied sections or views of your application, then probably you will end up with a lot of these calls distributed around. All of them with the same structure yet with several variants, such as:

val someIntent = Intent(context, SomeActivity::class.java)
//Do stuff with the intent
startActivity(someIntent)

//And if you don't do things with the intent and you are in an activity
startActivity(
    Intent(this, MyNextActivity::class.java)
)

My first problem

To be honest, there is no problem with this code. Not at all. But I have seen this happening in a lot of applications, firstly you have these calls distributed around without messed around, then you suddenly have 2 or 3 repetitions of the same work in different places, setting the same Intent with a different variable name but same parameters and then doing the same call. To solve these, most people usually do one of two things:

Wrap it around a single method for each case
Put all under a single class/object and just pass needed parameters for repeated cases

This means, for case 1:

/** Inside your class that will have the calls **/
fun startNext() {
    startActivity(
        Intent(this, MyNextActivity::class.java)
    )
}

fun startSome() {
    val someIntent = Intent(this, SomeActivity::class.java)
    //Do things with intent
    startActivity(someIntent)
}

And for case 2:

object AppRouter {
    fun startNext(context: Context) {
        startActivity(
            Intent(context, MyNextActivity::class.java)
        )
    }

    fun startSome(context: Context) {
        val someIntent = Intent(context, SomeActivity::class.java)
        //Do things with intent
        startActivity(someIntent)
    }
}

You can add several layers of complexity, but this is the base for most solutions: have a single point for launching/starting new activities. In my case, I always ended up having case 1 all around. Having functions here and there seemed like a good solution, until I ended with 120 functions doing almost the same all around, which is not bad, but seeing that ::class.java even inside of different methods really bothered me. Plus, seeing 3 or 4 functions inside the same class with almost the same body also feels wrong.

I wanted a way to remove that, to make that ::class.java disappear from everywhere and have something more explicit or at least more readable without the 123193 wrapper functions all around.

Generics

Coming from Java Land and seeing that all my function looked the same with one single parameter changed made me thing: "I can do better than this". So I did:

fun <T> launchActivity(context: Context, clazz: Class<T>) {
    val intent = Intent(context, clazz)
    startActivity(intent)
}

First problem solved: We have a single function to start our activities and we can leave it as a global function. As long as someone has access to a Context it can make use of this function. But…

Uncle Bob says that the less parameters, the better the function –and it's true, is easier to use it–
The ::class.java will still be present all around
If we want to hide the ::class.java and provide a more "business" related abstraction we still have a lot of functions

fun startNext(context: Context) {
    launchActivity(context, MyNextActivity::class.java)
}

fun startSome(context: Context) {
    launchActivity(context, SomeActivity::class.java)
}

And seeing this… well, the initial stuff that triggered me was the whole ::class.java and is still present, this is not a great improvement…

Inheritance

Well, having this global function also feels kind of wrong, and almost all the places using the function will be some kind of Activity. Maybe we can make the function available through inheritance…

open class BaseLaunchActivity: Activity() {
    fun <T> launchActivity(clazz: Class<T>) {
        val intent = Intent(this, clazz)
        startActivity(intent)
    }
}

//And then…
class MyActivity : BaseLaunchActivity() {
    fun onSomeClick() {
        launchActivity(SomeActivity::class.java)
    }
}

Cool! We got rid of one parameter, we hide where the magic is happening and made the function available to most of the parts using it.

But wait… most? We want all, not most… also this has other issues:

It is not always possible to inherit
Not all the classes in need of the code will be a kind of Activity
When some class has access to Activity it will need to be cast in an ugly way
::class.java is still present –ugh, it's ugly!

For the casting part we will have:

(getActivity() as BaseLaunchActivity).launchActivity(SomeActivity::class.java)

Which is TURBO-SUPER-ULTRA DANGEROUS –yes, I'm over reacting– because you can't be sure that from now and all the time, this cast will be successful. Why? Well, your class/component is depending on a container and the class itself does not have a mechanism to check all the time which type the container has –and even if it has it, it shouldn't be designed in that way– also if your functionality depends on the container being of some type… well, that's bad design.

Extension functions to the rescue

Depending on inheritance for this simply functionality seems like producing more problems. Other approach will be using an interface:

interface ActivityLauncher {
    fun <T> launchActivity(context: Context, clazz: Class<T>) {
        val intent = Intent(context, clazz)
        startActivity(intent)
    }
}

But we got back to having 2 parameters… BUT on interfaces we can enforce properties:

interface ActivityLauncher {
    val launcherContext: Context

    fun <T> launchActivity(clazz: Class<T>) {
        val intent = Intent(launcherContext, clazz)
        startActivity(intent)
    }
}

But now every class that needs this function will need to both:

Implement the interface
Give a value to the launcherContext property

That's boring!!

What about a single extension function to remove the dependency over the property?

fun <T> Context.launchActivity(clazz: Class<T>) {
    val intent = Intent(this, clazz)
    startActivity(intent)
}

That's actually cool!

Now whatever Context existing around can simply invoke this function without issues, we no longer need wrapper functions but… the ::class.java has not moved. Arghhh… that thing is making our code look ugly…

And we have a bigger problem… turns out that for this small function, the Kotlin compiler will generate some bytecode that once existing in the JVM will look approximately –on java– like this:

public final class ContextExtensions {
    public static final void launchActivity(@NotNull Context context, @NotNull Class clazz) {
        Intent intent = new Intent(context, clazz);
        startActivity(intent);
    }
}

This is not bad but is a caveat of having Kotlin extension functions and… well, if it is only to make things readable, we are not making too much progress: we only removed 1 line of code from our original block of code. What can save us from actually having this on the bytecode and still adding readability to our codebase?

INLINE

Adding a single reserved word to our function will make everything cool on the bytecode:

inline fun <T> Context.launchActivity(clazz: Class<T>) {
    val intent = Intent(this, clazz)
    startActivity(intent)
}

But if you are writing this on AndroidStudio or IntelliJ probably you'll notice a warning explaining that there's no actual optimization from inlining this function. And that's true, inline works as an SMART-COPY-PASTE which mean it will do magic on compile time to paste the body of your function where is being called with actual params and stuff.

Talking about params… what about the Intent? We usually pass information between activities using the Intent right? With the current approach is not possible to pass any parameter… let's fix that first and we then can check the warning from the inline.

Lambda with receiver

Because we don't want to increment the size of our parameter list, because the types of parameters can grow and because we don't want to have multiple wrapper functions just for the parameters, we need to find a way to "configure" our Intent on demand.

The lambda with receiver is one way to fix this. Adding this parameter to our function we can allow each caller to configure during execution of our function the Intent and still keep things readable:

inline fun <T> Context.launchActivity(clazz: Class<T>, confBlock: Intent.() -> Unit) {
    val intent = Intent(this, clazz)
    intent.confBlock()
    startActivity(intent)
}

Adding this last parameter we are saying that our function can take a lambda that will execute in the scope of an Intent and can use properties and methods from the Intent object. This lambda is later used to set up our Intent and finally we start the activity with the already configured Intent.

This change allows the execution to be something like:

fun onSomeInteraction() {
    launchActivity(SomeActivity::class.java) {
        putExtra(MY_KEY, myValue)
        putExtra(SOME_KEY, someValue)
    }
}

Also, the warning about inline disappears with these changes as the optimization now makes sense. In compile time, the compiler will take the call to our function and replace it with the actual body of the function and replacing the lambda with a local variable. This will increase a little bit the size of our bytecode but gave us more readability for usages.

The bytecode for this call on Java will look something like:

public void onSomeInteraction() {
    Intent intent = new Intent(this, SomeActivity.class);
    intent.putExtra(MY_KEY, myValue);
    intent.putExtra(SOME_KEY, someValue);
    startActivity(intent);
}

As you can see, no reference to external classes, no calls to external functions, all living there. This is a good thing, as the code stays simple while coding and has the real meaning when executing.

But still… while coding, the ::class.java is present. Why have I been complaining about this if it is something present in Kotlin? Well, the main reason is because this operator and class is not nice, it's quite ugly and also can be confusing. There is more than one way to obtain a Class<T> from a class and this one is the easier one. There's a chance for error using the other ones and they are verbose, not what we are trying to avoid here.

Reified for your types

We are currently having a generic – <T> – function that is inlined, these two elements can be combined to use a third element on our function: reified:

inline fun <reified Ty> Context.launchActivity(clazz: Class<T>, confBlock: Intent.() -> Unit) {
    val intent = Intent(this, clazz)
    intent.confBlock()
    startActivity(intent)
}

Adding this word will means that for every single call of our function, when inlining, the compiler will use the actual type instead of a generic or a super type in the caller –I'll go deeper on reified on next articles. This small change allows us to use the generic inside of our function as a real type, then we can remove the first parameter and replace with the real type:

inline fun <reified T> Context.launchActivity(confBlock: Intent.() -> Unit) {
    val intent = Intent(this, T::class.java)
    intent.confBlock()
    startActivity(intent)
}

Now all the calls to this function can be as clean as:

launchActivity<SomeActivity> {
    putExtra(MY_KEY, myValue)
}

launchActivity<MyNextActivity> {}

Some final touches to the signature will make the function even safer and even cooler when being called:

Make T have a constraint to Activity in a way only classes that extend from Activity are allowed
Add a default value to the lambda with receiver to allow calls with an empty configuration

inline fun <reified T: Activity> Context.launchActivity(confBlock: Intent.() -> Unit = {}) {
    ...
}

Now our function is cooler than ever, won't add too much to the final bytecode and also will make our code more readable. Wow! We traveled a long way doing a lot of changes to a single piece of code to make things cooler, but not just that, now other people developing along with us can benefit from this improvement as they can simply call our function without having to worry how it works. I have seen even people adding animations, making a way to hold results and transforming data using these kind of functions/approaches. Writing idiomatic Kotlin actually makes you think and develop different and cooler!

Conclusion

We can apply this kind of approach by steps or go directly to other functions on our codebase, one example is the usage of SharedPreferences and making the edition do an auto-apply "magically" using the lambda with receiver. We can create ways to configure more stuff in less steps and this will make our writing of code improve as we will be adding tools to our already-vast set of functions and tools on Kotlin. Thinking about what is repeated or can be improved allows us –the developers– to discover new worlds and make things cooler and sharper. Don't be scared of change.

Special thanks to my friends @annaelizleal, @jhoon and Alejandro Tellez, they help me a lot with grammar, typos and fixing styles. And special thanks to you for reading.

TDD with URM + Kotlin: Jump

Sinuhe Jaime — Sun, 21 Jul 2019 18:20:15 +0000

Here we are, once again, trying to build a URM interpreter.

This time we are going to take the hard part, the jump function. It should be easy right? Let's remember what the jump function does:

"It takes two positions as parameters and an instruction number. If the value of registers at positions are equal, then it moves execution to the instruction number"

What?!?

Relax, it's easier than you think. Let's see an example:

You have the the registry:

X: [,,4]

And the set of instructions:

1: Z(2)
2: J(2, 3, 10)
3: I(2)
4: J(2, 2, 2)

This set of instructions will only clone a number in a registry into another registry. In this case the registry at position 2 will end having the same value of registry 3. Don't believe me? No problem! Let's do a dry run seeing what happens in memory:

1: Z(2)        -> X: [,0,4]
2: J(2, 3, 10) -> X: [,0,4] // 0 != 4 so we continue execution at line 3
3: I(2)        -> X: [,1,4]
4: J(2, 2, 2)  -> X: [,1,4] // 1 == 1 comparing to the same position is always true, so we move back to line 2

2: J(2, 3, 10) -> X: [,1,4] // 1 != 4 so we continue execution at line 3
3: I(2)        -> X: [,2,4]
4: J(2, 2, 2)  -> X: [,2,4] // 2 == 2 comparing to the same position is always true, so we move back to line 2

2: J(2, 3, 10) -> X: [,2,4] // 2 != 4 so we continue execution at line 3
3: I(2)        -> X: [,3,4]
4: J(2, 2, 2)  -> X: [,3,4] // 3 == 3 comparing to the same position is always true, so we move back to line 2

2: J(2, 3, 10) -> X: [,3,4] // 3 != 4 so we continue execution at line 3
3: I(2)        -> X: [,4,4]
4: J(2, 2, 2)  -> X: [,4,4] // 4 == 4 comparing to the same position is always true, so we move back to line 2

2: J(2, 3, 10) -> X: [,3,4] // 4 == 4 so let's move to instruction 10… wait… there's no instruction 10, so we finish the execution

As you can see the J a.k.a jump function is a simple go-to in our machine. It moves the execution from one point to another. We need to create a way to represent this on our interpreter.

But first… tests

To begin with our jump function we need a test for it. We know the function will take a registry to fetch the values to compare and an integer to move the execution to that line. for now, we will pass the set of instructions to the function to allow the jump function to move the current index instruction.
We can take advantage of our other functions already created to setup some registers and then check the function works as expected:

@Test
fun `jump function should move to instruction X when registries are equal`() {
    zero(registry, 5)
    zero(registry, 10)

    jump(registry, 5, 10, instructionSet, 1)

    assertEquals(1, instructionSet.current)
}

Wow, that's actually an ugly function. It takes 5 parameters, probably Uncle Bob is looking at us and feeling disappointed… well, we will refactor it later. For now let's see if it works… well, actually we know it doesn't work, as we have seen previously, if we run gradle check to run the tests, it will generate a compile-time error because we haven't created the jump function yet.

Let's fix that:

fun jump(registry: Registry, positionX: Int, positionY: Int, instructionSet: ?, instruction: Int) {

}

Before moving on, we need to define how our instructionSet will behave or what type of data it will be. Things to keep in mind:

It should hold as many instructions as need it
Needs to know which is the current instruction and which one is the next one based on the index
Needs to easily change the pointer of execution to any other instruction

We could need more functionality from the instructionSet but having these 3 requirements tells us we need a class and that will let us at least write the minimum necessary to fulfill our failing test. First we need to change the test adding a type for instructionSet:

internal class OperationsTest {
    //…

    val instructionSet = InstructionSet()
}

And we can use it in the test, but wait, the test requires the instructionSet to have a current property. Let's create the class and add the property to remove the compile-time error:

class InstructionSet {
    var current: Int = 0
}

We use var because we will be setting the value to a different number on every execution of the instruction set. This class just holds data and actually doesn't need to do anything else for our current purpose. Our test should pass now, right? No compile time errors and it's quite straightforward.

Well, not exactly. If we run the classic: gradle check we will get:

expected: <1> but was: <0>
org.opentest4j.AssertionFailedError: expected: <1> but was: <0>
...

Hmmm we forgot to add an implementation to the function! Duh! Well… time to write the actual code:

fun jump(registry: Registry, positionX: Int, positionY: Int, instructionSet: InstructionSet, instruction: Int) {
    instructionSet.current = instruction
}

Easy peasy, now the test is passing! You can check it yourself. Please go to this commit, which contains all the code for this part and check it. It'll be worth it.

At this point you are probably thinking I'm crazy, but I'm not. This is a fair thing happening on TDD: you created a test, then you created code to pass the test, let's move on. No one said the implementation is right but the test is passing. We need to test deeper:

@Test
fun `jump function won't move to instruction X when registries are different`() {
    //Setup
    instructionSet.current = 3

    zero(registry, 5)
    zero(registry, 10)
    increment(registry, 10)

    jump(registry, 5, 10, instructionSet, 10)

    //Assertions
    assertNotEquals(10, instructionSet.current)
    //If the jump function did not matched it should go in the next instruction
    assertEquals(4, instructionSet.current)
}

Now if we check the project we will get a failing test! This means our other test was right in the way we wrote it but the implementation of the function is actually wrong. Let's fix that.
We need to validate that values at registers are equal, only then we will update the position on the instructionSet. Otherwise we should just continue execution on the next instruction. Adding the minimum to pass the test our test will pass again:

fun jump(registry: Registry, positionX: Int, positionY: Int, instructionSet: InstructionSet, instruction: Int) {
    val xValue = registry.getValueAtPosition(positionX)
    val yValue = registry.getValueAtPosition(positionY)

    if (xValue == yValue) {
        instructionSet.current = instruction
    } else {
        instructionSet.current++
    }
}

Conclusion

We finally figured out a way to do the jump function! We add the final tests and fixes to match the other operators of our URM (not included here, so you can do it as homework or cheat taking a look at the final code):

jump function cannot operate over negative positions (should throw an IllegalArgumentException)
jump function cannot work over empty registers (should throw an IllegalStateException)

This was quite easy and we can now move to the next part of our URM implementation.

We have some pending things that we will achieve later:

The jump function has 5 parameters. That's ugly
All the functions take a Registry as first parameter. We can fix that
This is not the final implementation, we will do a lot of refactors as it is part of the cycle of building with TDD
InstructionSet doesn't have operations and we should add tests if we add them
We are still using a stub Registry. We need to fix this later to make the tests more trustworthy
Tests are living code as well as our project, be open to fix and refactor our tests
Some tests fail from time to time because the data is in a wrong state, our Registry needs to reset on every test…

TDD with URM + Kotlin: Increment

Sinuhe Jaime — Wed, 10 Jul 2019 21:12:23 +0000

In the previous article we mentioned a way to start writing our implementation of URM using TDD. We also mentioned a lot of questions that came up while writing the zero function.

Now it's time to write the increment function.

Increment function

We know that the increment function will be I(x), where x represents a register in our Unlimited Register Machine. We are only writing only the internal that will be used to represent our functionality –for now.

Following the same approach we used for the zero function, we'll start by writing a test on how we expect the function to behave with negative numbers:

@ParameterizedTest
@ValueSource(ints = [-2, -8, -20, -100])
fun `increment function throws exception with negative position`(position: Int) {
    assertThrows<IllegalArgumentException> { increment(registry, position) }

    assertNull(registry.getValueAtPosition(position))
}

This initial test is in pro of the defensive model, but remember that we first need to make sure that the function fails for some invalid cases. We could start with a different part of the code but this is the easiest to write because we already wrote this on the zero function:

fun increment(registry: Registry, position: Int){
    require(position > 0) { "Position must be positive number" }
}

For our second test, we need to validate a "strict" rule: when a register has no value, it cannot be incremented. Our test should represent this and we should place a simple exception for it:

@ParameterizedTest
@ValueSource(ints = [2, 4, 20, 40])
fun `increment function cannot work with empty register`(position: Int) {
    assertThrows<IllegalStateException> { increment(registry, position) }

    assertNull(registry.getValueAtPosition(position))
}

If we run our test at this point, it will fail:

Expected java.lang.IllegalStateException to be thrown, but nothing was thrown.
org.opentest4j.AssertionFailedError: Expected java.lang.IllegalStateException to be thrown, but nothing was thrown.

This exception tells us what we already know: our function is not throwing the right exception for empty registers. Let's fix that by using the contract checkNotNull which is available on the kotlin stdlib (I'll write about contracts in another article):

fun increment(registry: Registry, position: Int){
    require(position > 0) { "Position must be positive number" }
    checkNotNull(registry.getValueAtPosition(position)) { "Register must be initialized" }
}

Now our tests are passing again. Let's write the actual implementation.

The real implementation

The test for the real implementation will need a little more setup. We know that the current approach will throw an exception if our test is just:

@ParameterizedTest
@ValueSource(ints = [11, 15, 110, 200, Int.MAX_VALUE])
fun `increment function adds 1 to value of position`(position: Int) {
    increment(registry, position)

    assertEquals(1, registry.getValueAtPosition(position))
}

This is because we wrote a test that will throw an exception when a registry does not contain a value and someone calls the increment function on it. But fortunately we already wrote tests for the zero function which means we can initialize our registry before calling increment:

@ParameterizedTest
@ValueSource(ints = [11, 15, 110, 200, Int.MAX_VALUE])
fun `increment function adds 1 to value of position`(position: Int) {
    zero(registry, position)
    increment(registry, position)

    assertEquals(1, registry.getValueAtPosition(position))
}

To fix the breaking test we need to modify our function:

fun increment(registry: Registry, position: Int) {
    require(position > 0) { "Position must be positive number" }

    val currentValue = registry.getValueAtPosition(position)
    checkNotNull(currentValue) { "Register must be initialized" }

    registry.setValueAtPosition(position, currentValue + 1)
}

We store the value of registry.getValueAtPosition(position) and then call the contract checkNotNull (I'll write about contracts soon, I promise!)

But testing with a single 1 is boring… Let's write something that operates over different values. To test dynamically we would need to check a parameter, then call increment and get an expected value. We could simply call assertEquals(parameter + 1, registry.getValueAtPosition(parameter)) but this somehow feels like cheating…

Using parameterized tests from JUnit 5 we can create a single test that will cover different cases in a single method, and we will use @CsvSource to pass different parameters. @CsvSource takes a group of comma-separated-strings for every set of parameters and our method will ask for this parameters in the appropiate types:

@ParameterizedTest
@CsvSource("50,1,2", "50,5,6", "50,100,101")
fun `increment function adds 1 to any integer value`(
    position: Int,
    original: Int,
    expected: Int
){
    registry.setValueAtPosition(position, original)

    increment(registry, position)

    assertEquals(expected, registry.getValueAtPosition(position))
}

This allows the test to be more dynamic and lets us add more cases having more flexibility!

Let's write one test mixing what we have learned:

@ParameterizedTest
@CsvSource("10,23,24", "15,99,100", "1000,1000,1001")
fun `check zero and increment can work together`(
    position: Int,
    original: Int,
    expected: Int
) {
    registry.setValueAtPosition(position, original)
    increment(registry, position)
    assertEquals(expected, registry.getValueAtPosition(position))

    zero(registry, position)
    assertEquals(0, registry.getValueAtPosition(position))

    increment(registry, position)
    assertEquals(1, registry.getValueAtPosition(position))
}

Wow! That's a test. We start by manually setting a value on a position. Then we increment it to assert that the increment works as expected -we know it does because we have a test to validate it!- and then we do something "new": we reset a register to 0. Here we are validating something we didn't check before: that the zero function can reset any registry regardless of the value. Finally, we increment and validate that increment works regardless of the value.

Conclusion

We added a new function and also validated that our previous work is not affecting the new code we just added. Everything was achieved through writing tests and fixing code!

There are still things that make the tests feel like cheating… calling manually registry.setValueAtPosition and having a custom implementation for example. We will fix this in the next article where we will talk about mocks!

Thanks for reading :)

TDD With URM and Kotlin

Sinuhe Jaime — Sat, 29 Jun 2019 18:36:48 +0000

In one of my previous articles I wrote about URM and how it works. In another one I mentioned test cases and how to keep ideas for a simple function. Now it's time to wrap up with TDD.

First of all…

What's TDD?

TDD is the acronym for Testing Driven Development. It works as a technique for building software based on first writing the tests for the given software.

It's worth to mention this technique does not solve all your the problems but allows you to identify problems before they get too messy. Also, it's a different way of writing code, which means it probably won't make total sense at first sight or won't stick too much with you. I think that once you get used to the process it will be easy to just go with it.

Some friends have complained about delivery times and the issue of TDD taking longer than just throwing a lot of code, the biggest argument about this being that if something breaks in the future and you don't have the tests for it, you would end up taking the same time fixing that as if you would have taken the time to do TDD since the begining. Still I think is worth the effort to learn why it is so popular and try it at least once —where once is a period of time bigger than 1 day.

TDD has only three rules to follow:

You are not allowed to write any production code unless it is to make a failing unit test pass
You are not allowed to write any more of a unit test than it is sufficient to fail; and compilation failures are still failures
You are not allowed to write any more production code than it is sufficient to pass the one failing unit test

With these three rules you can follow TDD kind of easily. The whole process involves more than just following these rules, as it involves changing mindsets. For the rules to work, you need to think as 3 different roles:

External developer
QA/Tester/Someone with partial knowledge of the design of the software
The actual developer

This means you'll be in a loop following the rules along with changing the current mindset. The whole process you would get use to, is here:

How would I like to use this code from outside the code? Would I like to have a way to pass a callback or would I get a value from the call? Which dependencies are needed before the actual call to the code?
Let's write code for validating that the response will work and that the value is returned/sent as it should be
Let's write the actual code
Refactor some names
Repeat from step 1 if something needs changing

The whole process for getting into TDD works differently for each person, and on a daily basis when you're facing tight deadlines it's also difficult to get used to it. Still, I insist: it's worth a try.

Project and setup

The accompanying project is a simple implementation of a working URM. The goal is to write a project capable of executing files in the URM notation:

X: []

1: Z(2)
2: Z(5)
3: I(2)
4: J(2,5,7)

As mentioned before, I'll be using Kotlin in the JVM flavor along with JUnit 5. I will also be using Gradle as the task runner and build tool. The final project can be found in this Github project

Zero function

The first thing we are going to build is the operations for the URM machine to work, this is the easiest part because we don't have to worry about the internals of the registers or the parsing process.

The Z(x) function will be our first feature to write. The function will take a number that represent a register position and will put a zero on it. We will build this function to be invoked in our code. It should be easy, right? Well… I have some questions:

Should the function be part of each register like: register.zero()?
- I dislike this idea, the registers should only know how to store a value, nothing else
- This would involve creating an object to represent each register, we don't need that complexity
Should the function be part of a bigger object like: URMinstance.zero()?
- This is a little improvement on where the function will live
- This approach has a problem, makes the function work only with the local group of registers (a.k.a registry) and having a bit knowledge of the implementation
- We depend on the existence of URMinstance to test the function (not as bad as I want to make it sound)
Which parameters should it actually take?
- The function should take the position of the register and should know about the group of registers in order to modify it
- The function should be agnostic of the way the registry is implemented but still know about how to set a value on it

With these questions and answers we decide on a simple way of calling our function:

zero(registry, position)

This way the function is not tied to a certain registry, it's not dependant on the inner implementation of the URM, and we can test it without involving too many things.

Our initial test

Our first test (in pseudocode) will be something close to:

position = 5

zero(registry, position)

checkEquals(0, registry.getPositionValue(position))

This is pretty close to our first kotlin test:

import org.junit.jupiter.api.Test

internal class OperationsTest {
    @DisplayName("Zero Function sets to 0 register at position")
    @Test
    fun zeroFunctionSetsTo0TheRegisterAtPosition() {
        val position = 5
        //val registry: ?

        zero(registry, position)

        val expected = 0
        val actual = registry[position]

        assertEquals(expected, actual)
    }
}

Using gradle we should be able to run the test:

sierisimo@computer:$ gradle check
…
e: /Dev/sierisimo/TDD_URM_Kotlin/src/test/kotlin/net/sierisimo/kurm/operations/OperationsTest.kt: (14, 9): Unresolved reference: zero
e: /Dev/sierisimo/TDD_URM_Kotlin/src/test/kotlin/net/sierisimo/kurm/operations/OperationsTest.kt: (14, 14): Unresolved reference: registry
e: /Dev/sierisimo/TDD_URM_Kotlin/src/test/kotlin/net/sierisimo/kurm/operations/OperationsTest.kt: (17, 22): Unresolved reference: registry
FAILURE: Build failed with an exception.
* What went wrong:
Execution failed for task ':compileTestKotlin'.
> Compilation error. See log for more details
* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.
* Get more help at https://help.gradle.org
BUILD FAILED in 9s
2 actionable tasks: 1 executed, 1 up-to-date
Compilation error. See log for more details

As we can see, we have a compilation error…

DUH! THAT'S OBVIOUS BECAUSE WE DIDN'T CREATE THAT FUNCTION, IT IS A VERY SIMPLE FUNCTION YOU DUMB…

Hey! Wait a minute… before saying that, you should remember the rules of TDD:

You are not allowed to write any production code unless it is to make a failing unit test pass
You are not allowed to write any more of a unit test than it is sufficient to fail; and compilation failures are failures
You are not allowed to write any more production code than it is sufficient to pass the one failing unit test

So that means I couldn't write the zero function before writing the test. But now we have a failing unit test, which means we are allowed to write production code!

Note: Production code can be a term that people understand as code that will be inmediatly put on a server/app to answer to user interactions. This is not 100% true, production code is basically code that will be on the final project and satisfies part of the functionality of the project.

Writing code and fixing

To write the code, let's hear what the errors have to say:

e: /Dev/sierisimo/TDD_URM_Kotlin/src/test/kotlin/net/sierisimo/kurm/operations/OperationsTest.kt: (14, 9): Unresolved reference: zero
e: /Dev/sierisimo/TDD_URM_Kotlin/src/test/kotlin/net/sierisimo/kurm/operations/OperationsTest.kt: (14, 14): Unresolved reference: registry
e: /Dev/sierisimo/TDD_URM_Kotlin/src/test/kotlin/net/sierisimo/kurm/operations/OperationsTest.kt: (17, 22): Unresolved reference: registry

This means we don't have a zero function! Let's create one in the package: net.sierisimo.kurm.operations.Operations.kt

fun zero(){

}

If we invoke gradle check again we get:

e: /Users/sierisimo/Documents/Dev/kurm/src/test/kotlin/net/sierisimo/kurm/operations/OperationsTest.kt: (15, 14): Too many arguments for public fun zero(): Unit defined in net.sierisimo.kurm.operations

Which means we forgot to add the arguments for the function. So our function will end looking like:

fun zero(registry: ?, position: Int){

}

I left something out in the function… what's the type of registry? Is it an array? I don't think so, our program is the "Unlimited Register Machine", and arrays have a limit size. Is it a list? Could be, as long as the list is initialized or has a way to grow to certain size to hold empty slots. The real question is: what functionality does the registry has? well, it should be able to retrieve the value of a register in a given position and set the value of a register in a given position. Then a list could work but still has the issue with empty slots.

We decide that, in this precise moment, we don't care about how the registry works, and because we don't care about how it works —as long as it works— we can create a definition for that:

interface Registry {
    fun getValueAtPosition(position: Int): Int?

    fun setValueAtPosition(position: Int, value: Int)
}

In that way, we can delegate later the responsability of the implementation. Now our first approach of the zero function goes like this:

fun zero(registry: Registry, position: Int) {

}

Since we don't care about the details of the registry itself, we can create an implementation on the test:

internal class OperationsTest {
    val registry = object : Registry {
        val positionValueMap = mutableMapOf<Int, Int>()

        override fun getValueAtPosition(position: Int): Int? = positionValueMap[position]

        override fun setValueAtPosition(position: Int, value: Int) {
            positionValueMap[position] = value
        }
    }

    @DisplayName("Zero Function sets to 0 register at position")
    @Test
    fun zeroFunctionSetsTo0TheRegisterAtPosition() {
        val position = 5

        zero(registry, position)

        val expected = 0
        val actual = registry.getValueAtPosition(position)

        assertEquals(expected, actual)
    }
}

This can be a final implementation, but writing this final implementation will violate the rules of TDD. We stay with this local implementation just for our test now.

If we run gradle check now it shows:

> Task :test

net.sierisimo.kurm.operations.OperationsTest > zero function should set a 0 in position X() FAILED
    org.opentest4j.AssertionFailedError at OperationsTest.kt:27

1 test completed, 1 failed

> Task :test FAILED

FAILURE: Build failed with an exception.

Which means the project successfully compiled but our test did not pass. And we know that we currently don't have a body in our function, let's fix that:

fun zero(registry: Registry, position: Int) {
    registry.setValueAtPosition(position, 0)
}

And finally gradle check will show:

> Task :test

net.sierisimo.kurm.operations.OperationsTest > zeroFunctionSetsTo0TheRegisterAtPosition() PASSED

BUILD SUCCESSFUL in 1s

A bad case

Our test is passing. Now we should write another test to validate everything works as expected. For example, we know that URM works with positions in registers, but what happens to negative positions? They are not valid positions… let's write a test for it:

@Test
@DisplayName("Zero Function throws exception with negative position")
fun zeroFunctionThrowsExceptionWithNegativePosition() {
    val position = -1

    assertThrows<IllegalArgumentException> { zero(registry, position) }

    assertNull(registry.getValueAtPosition(position))
}

In this test we check that our function doesn't work with negative positions. But also we state in the test we expect the function to throw an IllegalArgumentException. If we run the gradle check we will se this test is not passing, but the previous one is.

We fix the zero function adding Kotlin contracts:

fun zero(registry: Registry, position: Int) {
    require(position > 0) { "Position must be positive number" }

    registry.setValueAtPosition(position, 0)
}

Now if we run the check, both of our tests will be passing and we have made sure that even after we modified the way the function works internally, it works as expected for different scenarios.

Before moving into the next function, we should check for more cases, instead of having one method per case we go with parameterizing the test:

@ParameterizedTest
@ValueSource(ints = [1, 5, 10, 1000, Int.MAX_VALUE])
fun `zero function sets value to 0 at register in position`(position: Int) {
    zero(registry, position)

    val expected = 0
    val actual = registry.getValueAtPosition(position)

    assertEquals(expected, actual)
}

@ParameterizedTest
@ValueSource(ints = [-1, -5, -10, -1000, Int.MIN_VALUE])
fun `zero function throws exception with negative position`(position: Int) {
    assertThrows<IllegalArgumentException> { zero(registry, position) }

    assertNull(registry.getValueAtPosition(position))
}

We also take advantage of Kotlin support for function names with spaces using backticks to remove the @DisplayName and put directly the name in the function. And we can test our function just adding the values we want into @ValueSource(ints = []) without having to write more test cases.

Conclusion

For now, we have understood/learned the basics of following the process of design-test-check-fix-repeat loop of TDD. All of this with a simple function.

There's still so much to do, like creating tests for the other functions (increment, jump), but we are going to take that for the next article.

Thanks for reading!

Unit testing with JUnit

Sinuhe Jaime — Tue, 18 Jun 2019 18:50:28 +0000

I already explained that writing tests is not that hard
but I got some comments about it… I can summarize those comments in just one:

Where are the code examples?

So this time I will focus more in the code part with some simple examples.

Note: I won't follow TDD, BDD or any specific methodology thingy for this article. I want to explain how to think tests and how to write them as a first approach. Also worth to mention once more: I'll be providing most of the code in Kotlin for JVM, the concepts still apply for other tech.

Unit Tests

When you write code, you want to see it working, you want to see magic that formed in your mind working in the computer, you want to corroborate that everything is ready for the next steps in you NITRO-TURBO-SUPER-MEGA-AWESOME-PROJECT. But running the whole thing every single time, doing a compilation of the whole dependent code, passing previous screens/steps to arrive at the part you want to test, or simply adding one thousand logs as part of the process to check everything works is annoying and takes a lot of time. Also, you need to do this for every big change (or even smaller changes) to validate this new thing doesn't break other stuff.

Writing Unit tests can save you from this. A unit test is a single test that validates the smallest part of a system. It generally doesn't require too much setup and it is easy to read. Performing a unit test involves checking that one single functionality works as expected for both good and bad cases.

Let's begin with a simple (and classic) example: FizzBuzz.

The rules for FizzBuzz are quite simple:

A group of children are counting numbers, they go in turns and say something depending on the number they got:

When number is multiple of 3 they should say "Fizz" instead of the number

When number is multiple of 5 they should say "Buzz" instead of the number

When number is both multiple of 3 and 5 they should say "FizzBuzz" instead of the number

Otherwise they just say the number

These rules seem easy and fun, so how does it go for our code? Well, we decided to go for a simple function:

fun fizzBuzz(countUntil: Int): List<String>

This function will work correctly for every single element of the FizzBuzz game and will give us back the results. To keep the focus in the tests I removed the body of this function.

Our setup

Imagine that the previous function is located at filesystem in: project/src/main/kotlin/net/sierisimo/games/FizzBuzz.kt

Then our tests will be at: project/src/test/kotlin/net/sierisio/games/FizzBuzzTest.kt

This follows the standard of Java and is what Kotlin suggests in the official docs.

We are going to use JUnit 5 for our tests, so you should check the official docs if something's missing on this article. The only thing you need to know by now is that JUnit is a tool for running test frameworks on the JVM. It will help us run our tests and do some checks.

Let's write our tests cases!

Valid cases

First of all we need to focus on valid cases to check the function works as expected (quotes added to represent they are Strings):

When we pass the number 1 we should get back: ["1"]
When we pass the number 3 we should get back: ["1","2","Fizz"]
When we pass the number 5 we should get back: ["1","2","Fizz","4","Buzz"]
When we pass the number 60 we should get back: ["1", "2", "Fizz", "4", "Buzz", "Fizz", "7", "8", "Fizz", "Buzz", "11", "Fizz", "13", "14", "FizzBuzz", "16", "17", "Fizz", "19", "Buzz", "Fizz", "22", "23", "Fizz", "Buzz", "26", "Fizz", "28", "29", "FizzBuzz", "31", "32", "Fizz", "34", "Buzz", "Fizz", "37", "38", "Fizz", "Buzz", "41", "Fizz", "43", "44", "FizzBuzz", "46", "47", "Fizz", "49", "Buzz", "Fizz", "52", "53", "Fizz", "Buzz", "56", "Fizz", "58", "59", "FizzBuzz"]

This list can go on and on. For now we are going to stay with these four cases.

The first thing is to create a class that will hold our tests and set some methods on it to represent our valid cases:

import org.junit.jupiter.api.Test

class FizzBuzzTest {
    @Test
    fun whenWePass1WeGotASingleItemList() {
        //…
    }

    @Test
    fun whenWePass3TheLastItemIsFizz(){
        //…
    }

    @Test
    fun whenWePass5TheLastItemIsBuzz(){
        //…
    }

    @Test
    fun whenWePass60TheLastElementIsFizzBuzz(){
        //…
    }
}

Things you can notice in this class:

The annotation @Test before each method. This tells JUnit which methods are test cases and should run individually.
Names are longer and descriptive

There's also the chance in Kotlin along with JUnit 5 to use the backtick notation for method names:

internal class FizzBuzzTest {
    @Test
    fun `when 1 is passed a single item list is returned`() {
        //…
    }
}

Or if the names in this notation aren't what you like, you can also just use an annotation to put a fancy name on the test report:

@DisplayName("when 3 is passed the last item is 'Fizz'")
@Test
fun whenWePass3TheLastItemIsFizz(){
    //…
}

The style depends on you and there are even ways to make the displaying more fancy
or complex.

Once we have the tests, let's say what parts are involved in each one.

I generally think on a test like 3 parts:

@Test
fun myTestCase(){
  // Setup of data
  // Call to my SUT (System Under Test)
  // Assertions/Verifications
}

Our first test then goes:

@Test
fun when1IsPassedASingleItemListIsReturned() {
    //Setup of data:
    val limit = 1
    //Call
    val actual = fizzBuzz(limit)
    //Assertions/Verification
    assertTrue(actual.isNotEmpty())

    assertEquals(1, actual.size)
    assertEquals("1", actual.first())
}

If you run this on IntelliJ/Android Studio or with Gradle/Maven you will notice if your function is working.

The assertions like assertEquals and assertTrue are included with JUnit 5 but you can search the internet for other assertion libraries that include a more versatile and variant set of assertion (like AssertJ)

Here's a simple example of how the class can end with the tests:

package net.sierisimo.games

import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Assertions.assertTrue
import org.junit.jupiter.api.DisplayName
import org.junit.jupiter.api.Test

internal class FizzBuzzTest {
    @DisplayName("when 1 is passed a single item list is returned")
    @Test
    fun when1IsPassedASingleItemListIsReturned() {
        //Setup of data:
        val limit = 1
        //Call
        val actual = fizzBuzz(limit)
        //Assertions/Verification
        assertTrue(actual.isNotEmpty())

        assertEquals(1, actual.size)
        assertEquals("1", actual.first())
    }

    @DisplayName("when 3 is passed the last item is 'Fizz'")
    @Test
    fun whenWePass3TheLastItemIsFizz() {
        val limit = 3

        val expected = "Fizz"
        val actual = fizzBuzz(limit)

        assertTrue(actual.isNotEmpty())
        assertEquals(expected, actual.last())
    }

    @DisplayName("when 5 is passed the last item is 'Buzz'")
    @Test
    fun whenWePass5TheLastItemIsBuzz() {
        val limit = 5

        val expected = "Buzz"
        val actual = fizzBuzz(limit)

        assertTrue(actual.isNotEmpty())
        assertEquals(expected, actual.last())
    }

    @Test
    fun whenWePass60TheLastElementIsFizzBuzz() {
        val limit = 60

        val expected = "FizzBuzz"
        val actual = fizzBuzz(limit)

        assertTrue(actual.isNotEmpty())
        assertEquals(expected, actual.last())
    }
}

Invalid Cases

Testing for the happy path is great and shows that the function works correctly, but we know users don't work like that. They don't follow the happy path, they always try to break our stuff and they send weird stuff to our code.

The best thing we can do is to write tests for invalid cases too. The first ones that come to mind are:

Zero is not a valid parameter and the function should return an empty list: []
Negative numbers are not valid parameters and function should return empty list: []

Optional for other languages: Checking the data type is correct is also worth testing. In the case of Kotlin there's no need because this is checked at compile time.

These two cases are quite easy and we can even put them in a single test (and introduce new annotations):

@ParameterizedTest
@ValueSource(ints = [0, -1, -50, -1000, -123459, Int.MIN_VALUE])
fun whenLimitIsLessOrEqualThanZeroReturnsEmptyList(limit: Int) {
    val actual = fizzBuzz(limit)

    assertTrue(actual.isEmpty())
}

@ParameterizedTest allows the test to be executed multiple times passing the values found in @ValueSource individually to the test method. The test method then needs to take one parameter.

One big advantage of this kind of test is that we are now able to test all the invalid test cases we want with a single method and if a new case that behaves in the same way is needed we can just add it to the @ValueSource list.

Conclusion

This is just a simple introduction on how to write unit tests for a single function, things could get more complex when we need to pass more complex data or we need to test other kind of elements, but we can still see that testing is not that hard and we can easily validate the code we work with. If you are interested in the final test class it's available here, along with the markdown of this article.

Once more: Thanks for reading!

(And special thanks to Jhoon Saravia and Alejandro Tellez for helping me with grammar and typos)

My favorite computer theory to create examples

Sinuhe Jaime — Sat, 15 Jun 2019 21:37:10 +0000

In university I learned a lot of different stuff but one of my favorite topics in the "Computer Theory" class was URM (Unlimited Register Machine).

The theory

URM serves to demonstrate some concepts about computers and the computability of some operations. I won't go very deep into details of the history or theory, but it's similar to the theory of the Turin machine, which states that given a set of ordered instructions (called algorithm) and an infinite tape, the machine is capable of run that algorithm and give a result for valid inputs.

The registers

The registers in URM work much alike to an infinite sequential number of cells enumerated by position. You can only input numbers in the registers. The preconditions or information about this registers depends mostly on the author, but most agree that if the register hasn't been touched; it does not contain data. Other authors prefer to just go and say every register contains a zero before being touched by the machine.

The operations

To obtain a result of a computable algorithm (or demonstrate it's not computable) URM provides us with 3 basic operations. Some books or authors mention a fourth operation, but the fourth operations I have seen on paper are achievable with just the 3 basics ones (names or letters may vary depending on the author):

Z(position) Zero operation. Replaces whatever is in the register at position with a 0
I(position) Increment operation. Adds 1 to whatever is on the register at position. If we are strict… if nothing is at the register it cannot add 1 to it (so you need to invoke Z(position) first).
J(positionX, positionY, instruction) Jump operation. Compares the value of register at positionX and positionY, when the value is the same continues the execution at instruction. Is valid to send a instruction out of range, this will indicate the immediate end of the execution

The Instructions

This also varies from author to author, but the idea is the same: You have an ordered and identified list of calls for operations on registers representing your algorithm. Once the list ends, URM will stop.

Using a generic notation (there is not a formal or standard one), the list will look like:

1:  Z(5)
2:  I(5)
3:  Z(2)
4:  J(2, 5, 7)
5:  I(5)
6:  I(2)
7:  J(2, 2, 6)

The preconditions

It is also possible to provide preconditions to the machine to indicate a set of previously filled data, or how the algorithm works using variables (all lowercase):

X: [2,,,3]

Will indicate that the registers at position 0 and 3 started with a value. URM will proceed to read the instructions with this assumption and give a result.

X: [x,y]

Will indicate the existence of unknown numbers with names x and y . This will later execute with real values, the concept of variable does not exist in URM. There's also a chance to provide preconditions for the x and y like:

X: [x,y] -> x < y

This depends totally on the author and implementation. In most cases you state that on paper (or in some doc for your implementation).

The result

There's no formal indication on where the result will be. I created a small set of instructions to copy the result to the register at position 0. In that way you can check for a specific result in that position. Copying to different positions can get complicated but you can simply state that every set of functions works on different URMs (multiple machines). Some say this is cheating, but it helps if you want to reuse ideas. Remember this works in theory.

Example: Copy function

A set of instructions with the precondition of having a single number at register 1 and copying the value to the register 0

X: [,y]

1: J(0, 1, 6)
2: Z(0)
3: J(0, 1, 6)
4: I(0)
5: J(0, 0, 3)

You can then use this to invoke as a new operations (you will end up writing something similar but with different register position).

I wrote a small implementation of URM in JavaScript a few years back if you're interested in give it a check. It's code from when I was at university but still works (it has almost no dependencies).

This is something I wanted to share (and something I'll use for later examples) and I hope gives you the same amount of fun it gave to me. It's fun to code this as an exercise. I recommend you to give it a try (I know I will in Kotlin).

Testing… is not that hard

Sinuhe Jaime — Wed, 12 Jun 2019 05:42:20 +0000

(This is my first post in both English and Dev.to)

Testing… is not that hard

From time to time we need to talk about this topic. Most of us are familiar with it and we feel comfortable with writing tests, but the truth is that doing so is not a particularly popular topic.

In the past years, the tendency has been using some variant of cool techniques like TDD and BDD, and they are well applied; but most developers don't follow the rules or feel like the deadlines don't allow them to just write unit or integration tests. Geez… I even have heard some people say: "[sic] writing test is for QA teams right?"

Well… this is my attempt to show that testing is not that hard and can be an easy part of your daily workflow.

Notes:

I will refer to "function" when referring to methods or functions indistinctively, that kind of discussion for "the right name" is not relevant for this topic
Most of my work is on android, so this will probably be examples only in Kotlin/Java, but most of the concepts apply to other languages as well, like private in JavaScript can be functions not exposed in the module.exports

Why you should test

We, as developers, love writing a lot of code. We love making our lives miserably complicated using a lot of different things:

"I'm going to use X algorithm to sort these elements"
"We should add a hashcode function for it"
"That design pattern will solve all of our problems"
"Just use this tool for solving that small problem"

And from time to time we manage to get away with our solutions without problems. But time consumes everything, including code, and if you are on the need of using that code you wrote once for that small project and aren't sure if it will work… what will you do?

Testing can help us in a lot of ways. From the perspective of TDD fans we can say that: "testing helps us to not break things", which means that once we have tests, incoming new features/changes won't break the current code and from the TDD's perspective that's true. But not everyone follows TDD on a daily basis so we need a different perspective. For the everyday developer, testing is a way to "check if that thing just works". This means that we can validate that even, when new things arrive to the code (features or changes) the code is still usable and won't generate something unexpected or something weird that is not supposed to happen.

This is the main reason for tests. Testing is the way to go when we want to validate our work. I remember when I was at primary school, a professor showed us how to validate a result from different math operations and in that way we could check our results before giving her our homework. Testing is something similar. Testing is a way to do a check on our code, to validate that everything works as expected. Testing is like tasting the food you are cooking: you take a spoon, give it a little taste and if the flavor is not of your pleasing, you add and mix new things in the food until it gives you the result (taste) you want. You don't fix the spoon or you mouth to make the food taste better or as you want, you go and fix the food and try again with the spoon and with your mouth. Testing is the same, you fix your code, not the tests to make the code work as expected.

Note: Please taste the food you cook before putting it on plates for your guests. They'll appreciate it.

When we should test

While there's a common debate on what percentage of "test coverage" (or in human words "how much of the code has tests") you should get. My answer for this is: the most you can. You should try to write tests for most of the functionality of your code. There are still things you should keep in mind while trying to achieve good tests. For example, in my first time with tests I asked myself: "How can I be sure the test is well done or it will run as I intend to?" and my first thought was: "writing a test!", but obviously that's not the answer.

Writing tests for things you already have for taken for granted is bad idea. One example of this is writing a test for GSON (a famous java library from Google to parse JSON) and checking if it successfully parses a JSON. This is a bad idea because Google writes this library, obviously they already wrote some tests for the main functionality of the library so you are just messing with your time writing test for a well established library. Instead, what you probably want is to write a test for some class/function that uses GSON and that's a totally different case and is a valid one.

I ask myself these questions when I want to write a test:

Do I have control over this code and can change it freely?

Is this code that others can see and use externally?

If the answer is yes to both questions, then you probably need some tests for this fragment of code.

When to stop testing

There are cases that shouldn't be part of a test. One example in OOP is having a class that only represents data, i.e. in Java land it will be a POJO (Plain Old Java Object) and in Kotlin land it will be a data class, which has getters and setters. Writing a test for a getter or a setter is useless and should not be a case for a test. Tests should not be about the data itself but about the "what would happen with this data", and getters/setters are straightforwardly about what happens with the data.

Other cases that apply for no-tests-required are: private functions. This happens to be an actual discussion also in sites like StackOverflow. My personal opinion is that, if you have a very complex private function and you feel like you need tests for it, you probably need to split that function into smaller private functions and then check if they are really in need of being private or if they are in need of tests at all. This happens a lot in the OOP world and even in the scripting world, where developers face the needs of testing but they start getting complicated about structuring their tests. There are ways (like reflection in Java or @VisibleForTesting in android) to make things that are supposed to be private visible on tests. Still… I suggest avoiding this kind of testing, which involves tricks and cheats to obtain something supposedly not obtainable by simpler ways.

How you should test

Almost all languages include some way to enable test mode or they have tools created by other developers to test code. Even the worst thing I've used in my life (BrightScript for Roku) had a way to test over your code.

There's still things you should keep in mind while doing tests:

Have a contained environment. I don't want to talk about complex things (like containers or virtual environments like in python). What I mean by "a contained environment" is having a way to avoid your code communicating with sources outside of it. Like real databases or real web services. There are still parts of testing that involve communicating with these external sources, but even so, most of the environment should be contained (or controlled, whatever you want to call it)
Think about the worst cases. Yes, this is mostly the reason why we start writing tests. What happens if I get an unlisted data for my switch? What happens for empty lists or empty arrays? What happens if the user enters an emoji? What happens when the user doesn't speak english and it writes a non-english character? What's the limit for the text? What happens if the image server is down? etc. You should always think on the bad scenarios first and write tests for them. You'll get surprised about the results of writing this kind of tests
Think about the good cases. Once you fix all the issues with bad scenarios your code should still work properly and if not, then you should fix the code again to satisfy the bad and the good scenarios. Remember, Hope for the best, prepare for the worst
Think how others will use your code. When writing your tests think about how others will invoke your functions, which data will they use for that call, and what they are expecting as a result. Try to write your tests with this in mind, as real calls to your code and what could happen if someone sends the wrong parameters to your functions. Think about this scenarios in two perspectives: other developers and final users. Will a final user always enter his password right at first sight? Will a developer understand at first that complex Response object you return when they call your getProfile() function? Is Response the right name for that class? these are only examples of things you can face when writing tests, while trying to figure out if everything works as expected or if you will need to change things
Put scenarios in your mind. Create the whole scenario of a user and check which parts of your code are involved, then write that scenario as a test and validate that everything works as the scenario states it will
Don't be afraid of changing things. When writing tests you will notice that probably doing a call to a function is not that simple and you need a lot of data to perform that call. Well, write the test in a "happy path" way as you would expect it to be done, and then do a refactor of the code to work as the test says. Most of the time, you will end up adapting the code to pass the test, never the other way around. If you adapt a test to pass without changing the code, probably (most definitely) you are writing a false-positive
Don't overthink your tests. There is a moment for best practices and complex code. Writing tests is not that moment. A test should be straightforward about their intentions. It should be readable in a way that anyone without context of the code being tested can understand the intention of the said test

UPDATE: You can also give a check to this AWESOME article:

Different types of testing explained

jess unrein ・ Dec 6 '18

#testing #beginners #explainlikeimfive

Conclusion

Testing is as complex as writing code… because testing is also writing code. And if you like writing code, you should like writing tests as well, and validate that your code works as expected. Testing is not that hard, but it requires time and practice. In the end, it is as easy as writing regular code and will teach you more about your own code and what are the next steps for it.

There's still a lot more to say about testing and I'll be writing about it in future articles, and trying to update this one properly with links to other articles and examples.

Thanks for reading!