Every programmer was at some point confronted by this career-defining choice. But with this post today I'll expand the horizon and finally settle the debate.

So let's go over the different ways to indent your code and their pros and cons.

All of the pretty code images here were made using carbon.

Tabs

Indenting as ASCII intended. The pros of this technique are plenty:

• Every reader of the code can decide how much space it wants the IDE to attribute to one tab: 1, 5 or even 7 (sadly fractions are not supported by most).
• The resulting file size is smaller, ensuring that you can stay as productive as possible.
• You feel good giving purpose to the 10th ASCII character.

An image of code with tabs.

Spaces

Ah, the default for most editors. And also slightly more common than tabs in my objective experience.

The main advantage of this style is that you can force the reader of your code to use the same length of indentation that you used. I know I listed the opposite point as an advantage of using tabs, but we all know that in the end you cannot trust users – not even the users of an IDE.

Developers new to the discussion often bring up that this style requires you to press the space bar repeatedly. But of course noone actually does that – that's what auto-clickers are for.

An image of code with spaces.

Mixing tabs and spaces

Okay, hear me out: You can use tabs and spaces for different kinds of indentation.

For instance you could use tabs to indent blocks and then use spaces when you need something at a specific position, like when aligning the second parameter with the first.

An image of code with tabs and spaces.

This allows other people to still choose their own length for the tabs, but ensure that elements are still aligned when you want them to be.

Personally I also advocate to use tabs instead of spaces in between parameters, because that will create more visually pleasing code.

An image of code with tabs between parameters.

Mixing and mashing

For those that hate to be restricted by style guides and want to rebel against the bourgeoisie of coding, you can just do whatever you want and sometimes use tabs and sometimes use spaces.

This might seem weird, but if you look at the first projects of software engineers, you'll find that this is pretty common before they learn otherwise.

So it might just be the most natural of all of the indenting methods.

Plus, it turns programming into a small game, when, in every line, you'll wonder whether spaces or tabs were used.

And gamification improves cognitive, motivational and behavioral learning, so this method will also make you a better programmer in the long run.

An image of code with one line using a tab and the other using spaces. Can you guess which is which?

Lastly, you can actually fit two programs into one: Since the whitespace is ignored by most programing languages, you can use them to implement a separate program.

That makes for a great easter egg!

Comments

Instead of adding another program, you could also just try to use the space more efficiently. Since you'll likely decide to indent anyways, why let that space go to waste?

You can use block comments to add more useful information about what's happening in each line. That's especially useful for beginners so you don't forget to comment your code.

Since you don't want to use up too much space with full text comments all the time, I'd recommend using some well-defined short names.

Here are some suggestions by me:

An image of code with indentation comments.

This also increases searchability of your code since you can just search for "⏎" and find all of the returns in the file.

Semicolons

More and more language now move to a cleaner no-semicolons-required style.

Sadly some languages still haven't caught up.

But when you're using semicolons as indentation, you'll never have to worry about seeing one at the end of your statement ever again.

An image of code with semicolons as indentation.

Sadly some languages set (in my opinion) unreasonable restrictions on code when using this indentation style.

Java for instance will only allow you to use one indentation level for the line after a return statement. Otherwise it will complain about "unreachable code".

In those cases I'd recommend using a pre-compiler job that runs all of the files through a simple sed -r "s/;+/;/g" call, which will fix some of the errors.

Most languages also won't let you chain calls over multiple lines anymore.

I do see this as an absolute win, however, since I believe that no method should consist of more than one statement, anyways. That's usually a code smell.

Other languages will outright refuse to compile code indented like this completely.

While I don't believe that languages should unnecessarily restrict programmers, we're sometimes forced to work with such archaic languages. In that case, you could try to write a simple pre-compiler, publish it and then never maintain it for 3 years while racking up over a hundred thousand weekly downloads on NPM.

Right-to-left indentation

With i18n becoming more and more important, more any more programs introduce a RTL mode in which the text changes to be aligned from right-to-left.

Maybe it's time to also make that move in the code itself and indent to the right side instead?

The main advantage of this is that the maximum line width now becomes more than a suggestion and actually has to be respected.

An image of code with RTL indentation.

No Indentation

An often overlooked way of indentation is simply not indenting.

Has anyone ever checked if indentation actually improves readability? I know I haven't.

In fact, having no indentation forces you to read every line and ensures that you don't miss anything, reducing errors in the process.

Of course, we also save precious disk space.

An image of code with no indentation.

Blank space

What's better than no indentation? Nothing!

Blank space is the null to your empty list.

While most editors don't yet support this style, the up-and-coming OSS editor MEPaintIDE is pioneering this brand new way of styling your code.

Instead of doing the cumbersome, arduous, laborious work of inserting characters, you should take your code and push it somewhere else.

Code indented using blank space. I got a blank space, baby.

Summary

I think after this in-depth analysis we can agree that Paint is the best tool for beautiful indentation.

And I hope I could convince you that, at the very least, you shouldn't let people choose their indentation completely freely.

So let's look at why I think that these two classes actually have an impact on good code.

Cover image created by the author using Carbon.

Data classes lead to cleaner code

Kotlin's data classes are essentially just a quicker way to create POJOs. They generate getters, setters, hashcode, equals and toString automatically for you. Java 17 introduced something similar in the form of records, although there are some slight differences. Pretty much everything I'll say about them, also apply to records.

For those that don't know, the following is a data class:

data class Person(val name: String, var age: Int)

Without it, in pre-17 Java we'd have to write the following:

public class Person {
    private final String name;
    private int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    public String getName() {
        return name;
    }

    public int getAge() {
        return age;
    }

    public void setAge(int age) {
        this.age = age;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Person person = (Person) o;
        return age == person.age && Objects.equals(name, person.name);
    }

    @Override
    public int hashCode() {
        return Objects.hash(name, age);
    }

    @Override
    public String toString() {
        return "Person{" +
                "name='" + name + '\'' +
                ", age=" + age +
                '}';
    }
}

The obvious part is that we save a lot of code that has to be written and, worse than that, read. But the less obvious, but much more important difference is that changing something requires a lot of changes – some of which are easy to miss and likely won't cause any tests to fail. It's pretty easy to add a field and forget to also add it to the hashCode or equals method.

Making it hard to change or create a class also discourages programmers from doing so. For instance, in 99% of the cases having a boolean value in the constructor of a class means that that class should be split into two different ones. Yet, you'll find that in any bigger code base, simply because adding a boolean field takes around 5 minutes, while creating another class could take up to 20 if it's big. While 15 minutes might seem like a small price to pay for cleaner architecture, very few will actually choose that option.

Inline classes can make cleaner code performant (or even viable)

Inline classes are essentially as close to custom value types as you can currently get on the JVM. Let's say you have the following inline class: (example taken from the kotlin documentation).

@JvmInline
value class Name(val s: String) {
    init {
        require(s.length > 0) { }
    }

    val length: Int
        get() = s.length

    fun greet() {
        println("Hello, $s")
    }
}

Kotlin will then try to prevent the creation of an object as much as possible and instead use the raw type (in this case String). Instance method calls as well as property getters will then instead be compiled to static method calls.

The main reason why I like this is that it finally allows a performant way to implement tiny types. While I'm a big fan of that idea, I could never use it in any serious project since my job demands high performance standards, where the object churn of that technique in Java would be a very real problem. Nevertheless, I believe that the benefits are huge. And with the quick way to create a new class and the possibility to do that without creating an extreme amount of instances, this now becomes a very real and easy-to-implement style.

Downsides of inline classes

Sadly, I also see some downsides to inline classes:

1. They only work with one parameter. This is a major limitation, which means that when you need to group multiple values together, you'll still need to create an object every time.
2. It sometimes provides false security. When "instantiating" an inline class it's easy to think that it will never actually be created. However, in some cases that's not true. Mainly when it is being used as one of its interfaces or when it is used in a generic method.
3. They have to be final. Although I don't think this is a big problem as I don't see many reasons to extend a class with only one input field.

Summary

When comparing Java and Kotlin, data types and inline classes are usually just quickly mentioned as nice-to-haves. But I think that is really underselling them. They not only provide ways to reduce boilerplate code, but are also safer to use, can allow for a performant usage of tiny types and similar clean code styles and reduce the friction to crafting cleaner code – and friction is the enemy of good software.

Title photo created by Victor on picjumbo.

The perfect software that noone uses

I think we've all been there: You're randomly browsing the web and then find a interesting project. And it has everything you could want: It's fast, it looks good and has an extensive amount of features, even some that you wouldn't even have thought of.

But you're not gonna use it. Why? Because you have no need to. Maybe you want bar charts and the software only makes pie charts.

The problem is that you'd rather use imperfect, buggy software that in the end solves one of your pain points than use a perfect software, that does something else. But as a developer it's often easy to forget that.

You've done this before

Make things that people want to use.

That seems obvious doesn't it? Yet it's surprisingly common to disregard this.

Filling a specific need is the basis of every entrepreneurial endeavor, but more often than that I've seen it disregarded in APIs. Too often I've seen what should be a simple API turned into a complex one by the addition of too many (unnecessary) features.

I know that I'm guilty of doing this myself before: Sometimes it's so easy to make something more powerful than it needs to be that it's hard to resist. But there is multiple problems with doing that:

• It needs more time to develop.
• The API becomes harder to understand.
• The code itself becomes harder to understand.
• The API will be harder to extend. Even when the added complexity is making it more extensible, if you need to change it in a way that was not foreseen, you'll now have to extend a more complex system and maybe even need to do extra work to support the additional features that might not even be in use.

Especially when your API is far away from your actual end user, it becomes easy to forget about the internal user. Yet, I find user-focus just as important when they are your colleagues than when they are your paying customer.

How can we stop over-engineering?

This might be different for each person, but the processes in most software development frameworks like scrum already try to have built-in safeguards against this. Sometimes even explicitly in the form of non-requirements.

Personally, I try to follow the following steps even in private projects:

1. Specify exactly what I want to solve in this iteration. Usually this takes the form of a bullet list of 2-6 use cases.
2. See if it makes sense to split it up.
3. Write down how I would like to put my use cases into code.
4. Write the necessary interface for these code samples.
5. Think through how it would work and, if needed, add more inputs or outputs to the interfaces (e.g. you need user credentials after all; or you might have another error that you should report).
6. Implement these interfaces. If I realize that I can't, I go back to step 3 and not any later step.

These steps help me to keep the focus on the actual requirements and not some potential requirements. I find it especially important to return to step 3 if you're stuck at step 6. Because that is the easiest way to make changes that negatively influence the API usage afterwards.

And since it can be frustrating to not get to implement the "cool but unnecessary" ideas, I like to write them down. That way I don't feel like I'm completely disregarding them, but that I can simply implement them at a later point if I decide that they are useful additions.

These steps should of course be fitted into your current framework – for instance in scrum you'd probably make a refinement somewhere between step 1 and 4 depending on the style of the product owner.

Conclusion

This topic might be one of those things where you can feel the seniority of developers. Most lists about the mistakes of junior developers include a form of "don't do too much". I guess, once you've written enough cool code that no one ever used, it becomes less fun?

Anyways, one of the more important skills of software engineers, I find, is to have a good top-down view. Don't just understand how to make things work the best, but also understand how to help your user the best.

I’ll list them roughly in the order of most relevant to more fringe. I tried to find all of the differences that exist, but if I missed something, feel free to comment about it.

Title photo by Steve Harvey on Unsplash

Examples & why they matter

Before getting into the differences, I want to show some examples. If you already know how they work, you can skip this section.

Java’s records use the new key word record:

record Name(String firstName, String lastName) { }

Meanwhile, Kotlin’s data classes use the modifier data in front of the class:

data class Name(val firstName: String, val lastName: String)

Both automatically create most of the boilerplate code that you’d otherwise have to create: getters, setters, equals, hashcode and toString.

This not only helps reduce boilerplate code, but can also make refactoring safer, since now you don’t have to remember to add a new field to the now auto-generated methods.

Final classes

Both records and data classes will compile to final classes. For Kotlin, this is the default for all classes, but data classes cannot be declared open.

Mutable members

Java’s records are completely immutable. With data classes, however, you can specify which fields are mutable and which are not (as usual with the var vs val keywords). For example, in the following code, id cannot be reassigned, but name can be:

record Person(val id: Int, var name: Name)

In the case of immutable fields, it will mark them as final in the resulting code. Java’s records always have final fields.

Non-constructor fields

Records do not allow you to define additional instance fields, only static ones. With data classes, however, you can. These are, of course, not included in the automatically generated methods, but can be useful for some eagerly created values:

data class Name(val firstName: String, val lastName: String) {
    val fullName = firstName + ' ' + lastName
}

java.lang.Record

Java’s records now always implement the new class [java.lang.Record](https://download.java.net/java/early_access/jdk17/docs/api/java.base/java/lang/Record.html). This abstract class doesn’t add any interesting methods by itself, but can be used to catch all records.

This super class also means that records cannot extend other classes — although they can still implement interfaces. Data classes do not have this restriction.

Destructuring

Kotlin already supports destructuring for data classes. For Java, there is currently a proposal floating around, but no current version of Java (including Java 17) supports this syntax.

Kotlin’s destructuring

Kotlin has destructuring built into it’s assignment syntax. Given the Person class from before, I can now do the following:

val (id, name) = Person(0, Name("Oscar", "Ablinger"))

This will be compiled to two different assignment statements utilizing another set of auto-generated methods. It’s essentially syntactic sugar for the following two statements:

val id = person.component1()
val name = person.component2()

These two are typed, so the resulting variables will update their types when changing the field types. They also don’t have to be exhaustive, so when you add another filed, then the same code will still work.

This, however, means that if you add a field as anything but the last element and it shares the type with the field it replaced, the code will compile and no error will be given! This a a very hard to track down source of bugs.

toString

While both get an auto-generated toString method, the results look slightly different for Java and Kotlin. Java will generate the following string:

record Name(String firstName, String lastName) { }

new Name("Oscar", "Ablinger").toString();
// Name[firstName=Oscar, lastName=Ablinger]

Kotlin generates a similar string:

data class Name(val firstName: String, val lastName: String)

Name("Oscar", "Ablinger").toString()
// Name(firstName=Oscar, lastName=Ablinger)

As you can see, the only real difference is that Java uses square brackets while Kotlin uses parenthesis. Annoyingly enough, the default toString that IntelliJ generates for classes uses braces.

You could also use this generated string as basis for your style guide for the toString method.

Reflection

Data classes are essentially just syntactic sugar over normal classes. Therefore, once compiled, it’s pretty much impossible to tell them apart from other classes.

Records however can be easily recognized using reflection. Not only because they always implement the java.lang.Record type, but also thanks to two new methods added to Class: [isRecord](https://download.java.net/java/early_access/jdk17/docs/api/java.base/java/lang/Class.html#isRecord()) and [getRecordComponents](https://download.java.net/java/early_access/jdk17/docs/api/java.base/java/lang/Class.html#getRecordComponents()).

isRecord simply returns true if the class is a record and false otherwise.

getRecordComponents returns information about all of the fields of the record or null if it’s not a record. The term “component” is simply used to refer to the non-static fields of a record. Using this you have access to the same information that you’d expect from methods: annotations, name, type and more.

Getters

Kotlin generates getters after the well-known pattern with get prefix. Records now dropped this prefix and instead name the methods the same as the field.

Implementations

I already wrote about the different results of the toString methods. Additionally, the implementation of all of the methods is also done differently.

While the Kotlin compiler simply generates the code for each of the methods, Java outsources the actual code to a static method. The implementation of those methods simply call the [ObjectMethods.bootstrap](https://download.java.net/java/early_access/jdk17/docs/api/java.base/java/lang/runtime/ObjectMethods.html#bootstrap(java.lang.invoke.MethodHandles.Lookup,java.lang.String,java.lang.invoke.TypeDescriptor,java.lang.Class,java.lang.String,java.lang.invoke.MethodHandle...)) method with the necessary information. I assume this is done to reduce the byte size of records as much as possible.

Conclusion

In the end, data classes and records are pretty similar in their usage. But while data classes are simply syntactic sugar, records add a lot to the Java standard library. Nonetheless, data classes do allow for more features than records. Whether that’s a strictly good thing is a different debate.

Now, which one should you use?

First let me start by pointing out that Guava has many classes that interact with futures and are meant to be used along-side each other. So most of those classes don’t necessarily step on each others toes.

But first, let’s look at the vanilla Java implementations:

Title photo by Drew Graham on Unsplash

Future

Future is the base interface and is used by Java’s own CompletableFuture and most of the interfaces and classes of Guava. It’s been around since Java 5.

The interface is very rudimentary, only offering methods to check its status, cancel it or gett the result in a blocking way (optionally with timeout). This works for the simplest cases, but if you want to work with multiple Futures at once or maybe even chain operations, this interface alone quickly becomes tedious.

Some example code taken from the java documentation:

interface ArchiveSearcher { String search(String target); }
class App {

    ExecutorService executor = ...
    ArchiveSearcher searcher = ...

    void showSearch(final String) throws InterruptedException {

        Future<String> future
          = executor.submit(new Callable<String>() {
            public String call() {
                return searcher.search(target);
            }});

        displayOtherThings(); // do other things while searching

        try {
            displayText(future.get()); // use future
        } catch (ExecutionException ex) { cleanup(); return; }
    }
}

CompletableFuture

In Java 8 CompletableFuture and its interface CompletableTask were added to allow more powerful operations with futures. Those two are so tightly coupled that the interface can essentially be ignored.

CompletableFuture implements Future and also offers some more methods to work with the result:

• thenAccept allows you to register a function that will be called upon completion and whose result will be used for a new CompletableFuture that is returned from this method.

• exceptionally does the same as thenAccept, except that it is called when the CompletableFuture is completed exceptionally.

• handle allows you to handle both the success value as well as the exception in the same function.

• join will block until the CompletableFuture completes and either return the value or throw any of the occurring exceptions.

It also offers you some convenience methods to create CompletableFutures:

• supplyAsync let’s you specify a Supplier that will be called asynchronously and whose result will be the result of the CompletableFuture once finished.

• completedFuture will immediately return a successfully completed future. It’s counterpart failedFuture was added in Java 9.

Some example code:

public CompletableFuture<List<User>> loadActiveUsers() {

    return httpClient.<List<User>>sendAsync(request, bodyHandler)
        .thenApply(this::filterListOfUsersForActiveOnes)
        .exceptionally(throwable -> {
            LOG.warn(throwable);
            return List.of();
       });
}

public void displayListOfActiveUsers() {

    try {
        CompletableFuture<> activeUsersFuture = loadActiveUsers();
        displayOtherStuff();

        try {
            displayActiveUsers(activeUsersFuture.join());
        } catch (CompletionException e) {
            LOG.error(e);

            displayNoUsers();
        }
    }
}

Problems with CompletableFuture

While the fluent style of CompletableFuture is certainly a great improvement to the bare-bones approach of Future, it still has its quirks.

For one it’s easy to forget that it can also be canceled. This means that if you return a CompletableFuture the caller can cancel it! This might leave you with resources not being properly closed or an unexpected state. The easiest way to avoid this is to wrap your CompletableFuture in another one.

Another problem is also that exceptions are handled slightly inconsistently, which the documentation doesn’t mention:

NullPointerException exception = new NullPointerException(":(");

CompletableFuture.failedFuture(exception)
    .exceptionally(throwable -> {
        // here throwable is the exception from above
        return null;
    });

CompletableFuture.failedFuture(exception)
    .thenApply(Object::toString)
    .exceptionally(throwable -> {
        // here throwable is a CompletionException that wraps the
        //  exception from above
        return null;
    });

Lastly, handling only specific exceptions isn’t that easy. The function in exceptionally receives an instance of Throwable, which is a checked exception. This means you can’t re-throw it without first wrapping it in a RuntimeException, preferably a CompletionException.

While a CompletionException thrown in one of those methods is directly returned (for instance when using join), nested ones are not unwrapped. This means that you’ll likely end up with some boilerplate code like this:

.exceptionally(throwable -> {
    while (throwable instanceof CompletionException) {
        throwable = throwable.getCause();
    }

    if (throwable instanceof NullPointerException) {
        // handle the exception I care about
        return null;
    } else {
        throw new CompletionException(throwable);
    }
})

Futures

Moving away from the Java standard library, Guava’s static class Futures contains methods to more effectively work with Futures. It does so mostly by utilizing the ListenableFuture interface that we’ll look at next.

Notably, however, it also has a transform method that allows you to create a new future based on another one and a function. The new future will complete with the result of the provided one being transformed by the given function. This essentially mimics the way that CompletableFuture.thenApply works.

This class should be your first stop when trying to work with futures and Guava!

ListenableFuture

ListenableFuture is a simple interface in Guava that implements Future and only adds one method: addListener.

This method allows you to register listeners that are called once the future completes. Albeit they do not directly get the result, you may get it using the get method of the ListenableFuture itself.

This interface is the main one utilized in the Futures class. It is also implemented by most of Guava’s future classes.

ListenableFutureTask

This class is essentially a bare-bones implementation of the ListenableFuture interface. It has two factory methods using Callable or Runnable but otherwise only implements the methods of its interface.

SettableFuture

SettableFuture extends the methods of the ListenableFuture interface with setter methods. You can set its success value, exception or even set it based on another future.

This class is mainly useful for when you already have a thread on which you want to complete your future.

AbstractFuture

As the name implies AbstractFuture is an abstract implementation of the ListenableFuture interface. Beyond the already mentioned addListener and setters, it also has some methods that expose its internal state.

It’s unlikely that you’ll need this class, but it can be used to implement your own versions of ListenableFuture.

FluentFuture

FluentFuture is the most similar to Java’s CompletableFuture. It implements ListenableFuture and also offers mapping methods in transform and catching.

In this case catching allows catching specific exceptions, not just a Throwable. This enables a more selective approach to exception handling where the theoretical possibility of checked exceptions doesn’t result in a lot of boilerplate code.

Some example code taken from its documentation:

ListenableFuture<Boolean> adminIsLoggedIn =
     FluentFuture.from(usersDatabase.getAdminUser())
         .transform(User::getId, directExecutor())
         .transform(ActivityService::isLoggedIn, threadPool)
         .catching(RpcException.class, e -> false, directExecutor());

ClosingFuture

ClosingFuture is similar to FluentFuture, but acts more as a builder than a future itself. It offers methods to transform values, catch exceptions and combining multiple of them. At the end a ClosingFuture always has to be “finished”.

There is currently two ways you can finish it:

• finishToFuture will return a FluentFuture that will complete once all of the steps defined by the ClosingFuture are completed.

• finishToValueAndCloser will call a callback once finished.

An example from its documentation:

FluentFuture<UserName> userName =
     ClosingFuture.submit(
             closer -> closer.eventuallyClose(database.newTransaction(), closingExecutor),
             executor)
         .transformAsync((closer, transaction) -> transaction.queryClosingFuture("..."), executor)
         .transform((closer, result) -> result.get("userName"), directExecutor())
         .catching(DBException.class, e -> "no user", directExecutor())
         .finishToFuture();

Conclusion

When working with vanilla Java, your best bet is CompletableFuture. Once you also have Guava, you have a myriad of options to choose from. All of them fill slightly different niches and are meant for different levels of detail.

In the end, Guava’s many classes can quickly become overwhelming and confusing.

Personally, I’ll probably try out ClosingFuture and FluentFuture a bit more, but stick with CompletableFuture for now — mainly because I can safely stick it in APIs without having to worry about introducing a new dependency.

Title photo by Juan Camilo Guarin P on Unsplash

Immutable Collections

Guava has immutable implementations for all of Java’s common collections and of course its own collections. While Java does not have interfaces for it, it offers two methods to create immutable collections: [Collections.unmodifiableXXX](https://docs.oracle.com/javase/9/docs/api/java/util/Collections.html#unmodifiableCollection-java.util.Collection-) to wrap existing collections and [XXX.of](https://docs.oracle.com/javase/9/docs/api/java/util/List.html#of--) to create new ones.

I’ll take the example of ImmutableList, Collections.unmodifiableList and List.of for this post to simplify it, but the same things apply to all other versions.

An additional dependency

Using Guava will introduce a new dependency to your code. In my opinion it’s well worth it. Even if you choose to go with Java’s implementations for the examples here, Guava still offers many utilities that make it worthwhile.

A different story is including Guava classes in your public API. In that case you’d force every user of that API to use Guava and your specific version of it. You’re also locked out from removing it as a dependency.

This might be fine for libraries where you know that the users will also be using Guava, but even there it should generally be avoided.

An explicit tell

When you see ImmutableList somewhere, you know that that value is immutable. Not so much with Java’s methods, which will simply return a List.

This explicit tell is very useful:

• In parameters: The caller is guaranteed that the method won’t mutate the list. On the other hand, the user must first wrap their collection in an immutable one.

• In return values: The caller knows that this collection shouldn’t be mutated. It also helps the implementation since you can often avoid to create new instances and only update the list when needed. And you don’t have to look at the documentation of a method to figure out whether mutating the returned collection is fine.

• In fields and variables: When reading the code, it is immediately apparent that this field or variable isn’t and shouldn’t be mutated. This can help with some of the mental overhead. It also catches some potential errors at “linting-time”.

Less defensive copies

In order to better guarantee that a given list is not changed in a given context, it is common to create defensive copies. “Defensive copies” refers to the practice of first creating an immutable version of a given collection and then operating strictly on that one.

This practice can help ensure that a list isn’t mutated when it shouldn’t be. However, this will only be noticed at runtime and costs some runtime compared to using the list directly.

Using the immutable version directly as parameter might force the user to create an immutable version instead, but it also signals to them that it can be reused in other methods that also don’t mutate the list. This might result in less copies being generated, but it will definitely result in more clarity, since I don’t need to see the implementation in order to know whether the list will be mutated.

ImmutableList is truly immutable

Java’s Collections.unmodifiableList will only provide an immutable view on a collection. This is an important distinction.

First an foremost, this means that they aren’t truly immutable: They will change if the original instance is changed.

It also means that they won’t be able to take advantage of the immutability as much as Guava’s implementations can. They must still include unncessary concurrency checks, might allocate unnecessary space and more.

These differences are somewhat less relevant for the List.of method, which will create a new list anyways — even if the overload is used that takes an array of strings. However, it’s important to note that I couldn’t find this mentioned in any official documentation, so, technically, there is no guarantee that this will stay this way or is the same in all implementations.

Neither ImmutableList nor Java’s unmodifiable list prevent their elements from being modified, though. For that you’d have to create a deep copy. During my research, I stumbled upon this nice blog post outlining the differences in those approaches in a nice, visual way.

ImmutableList is a List

This is maybe less of an argument for Guava’s implementation and more so an important note: ImmutableList implements the List interface.

This means that you can use an instance of ImmutableList everywhere that you could use an unmodifiable list from Java.

There is one case to watch out for, though: When the called method creates a defensive copy using the Java methods. In that case it will create a new instance instead of reusing the old one, when you pass an ImmutableList. When provided Java’s unmodifiable list, it would instead simply use that instance directly.

The same is true in reverse: ImmutableList.copyOf will not create a new instance if a ImmutableList is passed to it, but will if an unmodifiable list is passed instead.

Implementing the List interface also means that they share one of the big problems: You can still call methods that would modify a collection. It will then only fail at runtime, not compile time. This is mitigated better by Guava’s version since they actively mark those methods as deprecated, which will show up in most editors. Of course this only works when using the raw ImmutableList and not when using it as List.

Verdict

I believe that Guava’s collections bring a lot of value compared to the Java standard library methods, so I would always use those if Guava is in the project. I might even consider adding Guava just for them, but luckily Guava has plenty of other good features that make justifying adding it pretty easy.

Optional

Before Java added Optional, Guava did. In this case, the probably best comparison is the one found in Guava’s own documentation:

A new Optional class was added for Java 8. The two classes are extremely similar, but incompatible (they cannot share a common supertype). All known differences are listed either here or with the relevant methods below.

• This class is serializable; java.util.Optional is not.
• java.util.Optional has the additional methods ifPresent, filter, flatMap, and orElseThrow.
• java.util offers the primitive-specialized versions OptionalInt, OptionalLong and OptionalDouble, the use of which is recommended; Guava does not have these. There are no plans to deprecate this class in the foreseeable future. However, we do gently recommend that you prefer the new, standard Java class whenever possible.

So by Google’s own recommendation, you should opt for the Java library version. I tend to agree, mainly because you can use that version safely in public APIs. The extra methods (mainly filter and flatMap) are a nice bonus, too.

Weirdly enough, for some reason, those two methods together with map are missing from their primitive counterparts. I guess Oracle didn’t think them useful enough.

Charset vs StandardCharset

These two are virtually the same. Both provide the same list of charsets as static fields: UTF-8, UTF-16, UTF-16BE, UTF-16LE, US-ASCII and ISO-8859–1.

It also helps that Guava’s documentation has this sentence for each of the constants:

Note for Java 7 and later: this constant should be treated as deprecated; use StandardCharsets.XXX instead.

So, for the same reason as with Optional, I’d recommend using Java’s versions instead.

Summary

In summary, I’d go with Guava’s version of immutable collections, but with the standard library versions of Optional and charsets. For the later two, there is just not enough reason to use a library over the existing one.

To recap, the reasons for the immutable collections are:

• An explicit tell that something is immutable.

• They can be used as a simple List just the same as Java’s implementation.

• They aren’t modified if the source collection is modified (if one exists).

• They can use the immutability to their advantage when implementing the collections. This means sometimes better runtime of methods and less required memory.

However, they also have some negatives:

• They require an extra dependency, which is especially problematic if you want to use the classes/methods in public APIs.

• They still have the same problems that come from implementing List.

One last note: Guava also has its own ways to work with futures, while Java now has CompletableFuture. This topic deserves its own blog post, however, so I have written one here.

Title Image made by the author using mermaid.js

The Problem of Exceptions

Look at the following Java code and tell me what it could return:

public String getCurrentUsername() {
    User user = getCurrentUser();
    return user.getUsername();
}

On the first look, this method could return a String, null or throw a NullPointerException, if getCurrentUser returns null.

But that’s not all, it could also throw any other unchecked exception. Maybe getCurrentUser returns an IllegalStateException, because some initialization is missing?

For the username it might be harmless, but what about the following?

public void unloadAllCachesOfUser(UserId userId) {
    Collection<Cache> caches = getCachesOfUser(userId);
    if (caches != null) {
        for (Cache cache : caches) {
            cache.unload();
        }
    }
}

This kind of code can easily sneak through code reviews. But what if any one of the cache unloads throws an exception? In that case all of the other caches wouldn’t be unloaded and if Cache is an interface, it isn’t even clear what exceptions could be thrown.

This mistake is so common that many languages nowadays have a version of the [try-with-resourses](https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html) statement. Usually, they are used for file streams or connections to ensure that they are closed properly. But it’s easy to overlook for other cases, where it’s fine most of the time. Be honest: how often do you think about “What if this method throws an exception?”

Exceptions are worse than gotos (in some ways)

Back to the original story. I don’t know what answer we came up with back then, but this is what I’d say now:

They are similar, but there are a few differences:

1. I can send some data with it,

2. I can contain it when calling a method (by wrapping it in a try-catch), and

3. I don’t know where I’ll be going.

The last one is a pretty big deal: When you see a throw statement, you don’t immediately know, what code will be executed next. Worse even, sometimes you can’t know, because the method could be called from multiple sources.

When writing a method this is perfectly fine — the method does one thing and that’s all we should care about. We should ignore the context around it for the most part anyway.

But when reviewing code, this can quickly become hard to understand/read. And how would I make sure that all callers of my method properly handle it?

Which leads to the problem of the previous example: How do I know what exceptions a method can return? And the answer is, that I’d have to read all of the code that that method might use and look for throw statements. Then I need to see if they’re handled or not. Even some libraries with otherwise good documentation like to keep an air of mystery around which exceptions are thrown and when.

Exceptions are better than gotos (in some ways)

So why are exceptions then commonly accepted, while gotos are almost universally avoided?

The answer is the first two points in the previous section. If used correctly, exceptions aren’t that bad.

You can catch exceptions

Unlike gotos, the caller of a function can actually interact with exceptions. You can ensure that even if an exception is thrown, you get a chance to close a file stream, close a connection or still execute some code to prevent an illegal state.

This already mitigates a big part of the danger of gotos as I can make sure that certain code is executed in any event.

You can send some data with it

Sending additional information about why this jump outside of the regular flow is made can give considerate context to it. Instead of just telling you which code should be executed next, it tells you what happened.

Of course, this can be abused. Exceptions can now also be used as an additional return value of functions — and sadly, often are. There is this idea to not use exceptions for flow control, but all exceptions necessarily control the flow of a program. You just need to make sure that an exception is actually the exception.

The alternative

So what should we’ve learned instead to replace all of the -1s and nullptrs?

One of my favorite things to make an API safer and easier to use is extending its domain. What I mean by that is that it takes any error states and handles them the same way that it would success returns: It accepts it as valid input and presents it to the user, in the same way, encouraging and sometimes forcing a user to gracefully handle them both.

This can be done generically with the Result type (also sometimes called Throw or Either). A very basic implementation is below:

public static class Result<T> {
    private Object value;
    private boolean isSuccess;

    private Result(Object value, boolean isSuccess) {
        this.value = value;
        this.isSuccess = isSuccess;
    }

    public static <T> Result<T> success(T successValue) {
        return new Result(successValue, true);
    }

    public static <T> Result<T> failure(Throwable ex) {
        return new Result(ex, false);
    }

    public <R> Result<R> flatMap(Function<T, Result<R>> transform) {
        if (isSuccess) {
            return transform.apply((T)value);
        } else {
            return (Result<R>) this;
        }
    }

    public void onFailure(Consumer<Throwable> handler) {
        if (!isSuccess) {
            handler.accept((Throwable)value);
        }
    }
}

The implementation is very basic and if you want to use it, you’d probably want to add more utility functions, but the idea is there: The user gets a Result instance, so he already knows that it could either have a success state or a failure state, and as such, he cannot forget about either of them.

Ideally, you wouldn’t use a generic Throwable but actual objects that are tailored to the different errors that can appear in any given function. In a way, Optional (also often called Maybe in other languages) are a special form of Result.

This approach has many advantages:

• Users cannot forget about errors,

• the api can explicitly list all possible errors and their values without bloating the function itself or relying on documentation and

• it is more apparent where failures are handled.

This monadic way of handling exceptional states can already be found in many newer apis: Linq in C#, Streams in Java, Promises in JavaScript and many more

So, should you replace all exceptions with results?

If we want to wrap a function that potentially throws errors with the result type, it would look like this:

public Result<String> wrappedFunction() {
    try {
        return Result.success(unwrappedFunction());
    } catch(Throwable ex) {
        return Result.failure(ex);
    }
}

That’s quite a bit of boilerplate code that would have to be repeated for almost every third party function and functions from the standard library. Sure, you can create a generic wrapping function, but is it really worth it?

Honestly, for most cases I don’t think so. I try to avoid creating new exceptions whenever possible, but I wouldn’t go through the effort of wrapping already existing functions just so I can avoid them. If anything, this should’ve been addressed by the language itself.

Not every exception is worth caring about

Code like b/c might throw an ArithmeticException if c is 0. But we need to address this only if we didn’t first check that this cannot be the case. With exceptions we can ignore it by just simply doing nothing. Most likely we’ll eventually fall into a catch-all that logs the issue and tells the programmer to check this.

With the Result type, we have to explicitly ignore it, so we’re automatically prompted to check whether that’s possible. This might result in some additional unnecessary code, but it makes it just a bit more resilient.

Summary

If we’d learned about Result types rather than exceptions, I believe, our reaction would’ve largely been the same. They might even be slightly easier to learn and as such would’ve been introduced earlier.

That doesn’t mean that exceptions are actually as bad as gotos. But they are frighteningly close for how common they are. And I’ve definitely wasted hours before when trying to figure out what exceptions a library method might throw. And of course I’ve also overlooked some of them before.

Maybe even worse, exceptions can easily be misused as a way to return multiple different return values. And sadly, I’ve seen this done before.

Personally, I wish that more languages would adopt this more “functional” style of error handling instead of exceptions (like rust already did). I believe that many errors can be prevented in this way.

Resources

If you want to play with my cache example and Return a bit, you can do so on this online-java doodle.

If you want to play around with my beautiful mermaid diagram, you can press this link.

Made by the author using carbon.sh

Usage

Before showing you the script, I first want to show you what you can do with it.

By default this script automatically figures out the commit a changed file was last modified in and creates fixup commits for them. There will only be one fixup commit for one original commit, even if multiple changed files were modified in the same one.

You should be able to squash all of the generated commits without a merge conflict (using git rebase -i).

Additionally, you can also tweak its behavior a bit with some options:

• The plain text parameter “root”: This script will only look at commits starting from (but excluding) the root commit. This can be used to ensure that no fixup commits will be created for commits that aren’t on the current branch. Files that were last changed in or before this commit will simply be left uncommitted.

• -n | --dry-run: If dry run is specified no lasting changes are made. Instead it will just output which files it would assign to which commits.

• -d | --default-root Specifies the default root. If both the default root and root are specified, only root is considered. This is meant for a git alias, where you can specify main or master as default and still overwrite it when using the alias.

• -M<n> | --find-renames[=<n>]: If specified, will attempt to also assign renames. The format is the same as for git diff.

For example, let’s look at the following command:

assign -n -d main -M master

This will cause the script to list the commits for all changed files (instead of creating commits thanks to -n) including renamed files (due to -M). It will not list files if their last changed commit was made before or in the commit that the current master is on (would be main with just the -d option, but it was overwritten by the last parameter).

See the next chapter for an example output.

Example

To test this, I also made a small script that creates a git repository and adds some commits to it.

#!/bin/sh

rm -rf repo
mkdir repo
cd repo

git init

echo "* text eol=lf" > .gitattributes
git add .
git commit -m "initial commit"
git checkout -b "feature-branch"

echo a > A
git add .
git commit -m "A"

echo b > B
git add .
git commit -m "B"

echo with spaces > "file with spaces"
git add .
git commit -m "file with spaces"

echo aAndC >> B
echo c > C
git add .
git commit -m "B and C"

echo change > A
echo change > B
echo change > C
mv "file with spaces" "other file with spaces"

This will create a few commits and some uncommitted changes:

Screenshot of the git for windows bash made by the author

If I now execute assign -M -d main -n in that repository, the output will look like this:

Screenshot of the git for windows bash made by the author

Note that in this screenshot, I already took advantage of a git alias that I’ll show you in the end.

The code

Okay, enough explanation, here is the code:

#!/bin/bash

# Usage information:
#   assign [-n | --dry-run] [-d | --default-root] [-M[<n>] | --find-renames[=<n>]] [<root>]
# 
#   -n | --dry-run:
#       If dry run is specified no lasting changes are made.
#       Instead it will just output which files it would assign to which commits
#   -d | --default-root:
#       Specifies the default root.
#       If both the default root and root are specified, only root is considered.
#       This is meant for a git alias, where you can specify 'main' or 'master' as default
#       and still overwrite it when using the alias.
#   -M[<n>] | --find-renames[=<n>]:
#       If specified, will attempt to also assign renames.
#       The format is the same as for git diff.
#       (see https://git-scm.com/docs/git-diff#Documentation/git-diff.txt--Mltngt)
#   root:
#       This script will only look at commits starting from (but excluding) the root commit.
#       This can be used to ensure that no fixup commits will be created for commits that
#       aren't on the current branch.
#       Files that were last changed in or before this commit will simply be left uncomitted.

# Default options
DRY_RUN=false
DEFAULT_ROOT=""
ROOT=""
FIND_RENAMES=()

# Read potential options
while [ "$1" != "" ];
do
    case $1 in
        -n | --dry-run)
            DRY_RUN=true
            ;;
        -d | --default-root)
            shift
            DEFAULT_ROOT="$1"
            ;;
        -M* | --find-renames*)
            FIND_RENAMES=("$1")
            ;;
        -*)
            printf "unrecognised option: %s" "$1"
            exit 1
            ;;
        *)
            if [[ $ROOT == "" ]];
            then
                ROOT="$1"
            else
                printf "Cannot specify root twice (specified both '%s' and '%s')" "${ROOT}" "$1"
                exit 1
            fi
            ;;
    esac
    shift
done

if [[ $DEFAULT_ROOT != "" && $ROOT == "" ]];
then
    ROOT="${DEFAULT_ROOT}"
fi

# For each changed file find the commit in which it was last changed.
# lastCommits is an associative array with the commit hash as key and
# a newline separated list of the file names as value.
declare -A lastCommits
IFS=$'\n'; for file in $(git diff --name-only);
do
    if [[ $ROOT != "" ]];
    then
        commit=$(git log -1 --format="format:%H" "${ROOT}.." -- "${file}")

        # When a root is specified, a file could have no changes before that.
        # We simply ignore that file then.
        if [[ $commit != "" ]];
        then
            lastCommits[$commit]+="$file"$'\n'
        fi
    else
        commit=$(git log -1 --format="format:%H" -- "${file}")
        lastCommits["$commit"]+="$file"$'\n'
    fi
done

declare -A renamedFiles=()
if (( ${#FIND_RENAMES[@]} ));
then
    # first add all files indvidually as intent-to-add
    intentToAdd=$(git ls-files -oX .gitignore)
    for file in $intentToAdd;
    do
        git add -N "$file"
    done

    # get all renames and save them into an associative array
    while IFS=$'\t' read -r origFile newFile;
    do
        renamedFiles["$origFile"]="$newFile"
    done < <(git diff --name-status --diff-filter=R "${FIND_RENAMES[@]}" | cut -f 2,3)

    # remove intent-to-add
    for file in $intentToAdd;
    do
        git reset -q -- "$file"
    done
fi

# For each commit in lastCommits, we now add all of the associated
# files and then create a fixup commit for the respective commit

add_file() {
    if [[ $DRY_RUN == false ]];
    then
        git add "$1"
    else
        printf "\t%s\n" "$1"
    fi
}


IFS=$'\n'
for commit in "${!lastCommits[@]}";
do
    if [[ $DRY_RUN == true ]];
    then
        printf "%s\n" "$(git log -1 --color --format="format:%C(auto)%h%d%Creset: (%aN) %s" "${commit}")"
    fi

    for file in ${lastCommits[$commit]};
    do
        add_file "$file"
        if [[ -v "renamedFiles[${file}]" ]];
        then
            add_file "${renamedFiles[${file}]}"
        fi
    done

    if [[ $DRY_RUN == false ]];
    then
        git commit --fixup "${commit}"
    fi
done
unset IFS

It’s a lot, but luckily you can just copy-paste it into a file on your computer. And instead of always calling the file directly, I’d recommend making a git alias for it.

I did this by adding the following to my ~/.gitconfig file:

[alias]
 a = assign
 assign = !bash -c '~/.gitscripts/assign -M -d "$(git merge-base HEAD main)" "$@"' -
 assign-all = !bash -c '~/.gitscripts/assign -M "$@"' -

Of course you might want to change the default options for your aliases a bit (e.g. changing main to master), but I find that those are the most sensible defaults for me. Just don’t forget to replace the path to your script (in my case I saved it as ~/.gitscripts/assign).

Oh, and no guarantees if your file names have newlines or tabs in them.

Explanation

If you just want to use it, you can stop reading now. But if you’re curious how it works, here is an incremental explanation:

The simplest script

At first I just wanted to have a script that automatically creates fixup commits based on the last commit a changed file was modified in. I came up with a simple 5-line script:

for file in $(git diff --name-only);
do
    git add "${file}"
    git commit --fixup "$(git log -1 --format="format:%H" -- "${file}")"
done

Pretty simple, right? Go through each changed file, add it and create a fixup commit.

The simple script

But the previous script will potentially create multiple fixup commits for the same commit. I thought that was ugly, so instead of directly adding and committing, we’re first creating a map of commits to its changed files.

#!/bin/bash

# For each changed file find the commit in which it was last changed.
# lastCommits is an associative array with the commit hash as key and
# a newline separated list of the file names as value.
declare -A lastCommits
for file in $(git diff --name-only);
do
    commit=$(git log -1 --format="format:%H" -- "${file}")
    lastCommits[$commit]+="$file"$'\n'
done

# For each commit in lastCommits, we now add all of the associated
# files and then create a fixup commit for the respective commit
IFS=$'\n'
for commit in "${!lastCommits[@]}";
do
    for file in ${lastCommits[$commit]};
    do
        git add "${file}"
    done

    git commit --fixup "$commit"
done
unset IFS

Adding some options

Next I wanted the ability to have a dry run for the times, where I’m not sure whether the last commit is actually the correct one. So I added a bit more command parsing boilerplate at the beginning and some if statements.

#!/bin/bash

# Default options
DRY_RUN=false

# Read potential options
while [ "$1" != "" ];
do
    case $1 in
        -n | --dry-run)
            DRY_RUN=true
            ;;
        *)
            printf "unrecognised option: %s" "$1"
            exit 1
            ;;
    esac
    shift
done

# For each changed file find the commit in which it was last changed.
# lastCommits is an associative array with the commit hash as key and
# a newline separated list of the file names as value.
declare -A lastCommits
for file in $(git diff --name-only);
do
    commit=$(git log -1 --format="format:%H" -- "${file}")
    lastCommits[$commit]+="$file"$'\n'
done

# For each commit in lastCommits, we now add all of the associated
# files and then create a fixup commit for the respective commit
IFS=$'\n'
for commit in "${!lastCommits[@]}";
do
    if [[ $DRY_RUN == true ]];
    then
        printf "commit %s:\n" "${commit}"
    fi

for file in ${lastCommits[$commit]};
    do
        if [[ $DRY_RUN == false ]];
        then
            git add "${file}"
        else
            printf "\t%s\n" "${file}"
        fi
    done

if [[ $DRY_RUN == false ]];
    then
        git commit --fixup "${commit}"
    fi
done
unset IFS

Adding the root options

In order to add the root option(s), I extended the boilerplate code at the beginning. After the options are read, the root is set to either the default root or the specific root.

Now, when figuring out which files belong to which commit in the first loop, we just also specify the root commit (if we have one). This will cause git log to return empty if it finds no relevant commit after the specified commit.

No other changes are required.

#!/bin/bash

# Default options
DRY_RUN=false
DEFAULT_ROOT=""
ROOT=""

# Read potential options
while [ "$1" != "" ];
do
    case $1 in
        -n | --dry-run)
            DRY_RUN=true
            ;;
        -d | --default-root)
            shift
            DEFAULT_ROOT="$1"
            ;;
        -*)
            printf "unrecognised option: %s" "$1"
            exit 1
            ;;
        *)
            if [[ $ROOT == "" ]];
            then
                ROOT="$1"
            else
                printf "Cannot specify root twice (specified both '%s' and '%s')" "${ROOT}" "$1"
                exit 1
            fi
            ;;
    esac
    shift
done

if [[ $DEFAULT_ROOT != "" && $ROOT == "" ]];
then
    ROOT="${DEFAULT_ROOT}"
fi

# For each changed file find the commit in which it was last changed.
# lastCommits is an associative array with the commit hash as key and
# a newline separated list of the file names as value.
declare -A lastCommits
for file in $(git diff --name-only);
do
    if [[ $ROOT != "" ]];
    then
        commit=$(git log -1 --format="format:%H" "${ROOT}.." -- "${file}")

        # When a root is specified, a file could have no changes before that.
        # We simply ignore that file then.
        if [[ $commit != "" ]];
        then
            lastCommits[$commit]+="$file"$'\n'
        fi
    else
        commit=$(git log -1 --format="format:%H" -- "${file}")
        lastCommits[$commit]+="$file"$'\n'
    fi
done

Adding find-renames

The previous script works pretty well already. The only annoying thing is that if I rename a file, it will only create a fixup commit for the deletion of the original file, but not for the adding of the “new” file.

So I added a new option:

# Default options
DRY_RUN=false
DEFAULT_ROOT=""
ROOT=""
FIND_RENAMES=()

# Read potential options
while [ "$1" != "" ];
do
    case $1 in
        -n | --dry-run)
            DRY_RUN=true
            ;;
        -d | --default-root)
            shift
            DEFAULT_ROOT="$1"
            ;;
        -M* | --find-renames*)
            FIND_RENAMES=("$1")
            ;;
        -*)
            printf "unrecognised option: %s" "$1"
            exit 1
            ;;
        *)
            if [[ $ROOT == "" ]];
            then
                ROOT="$1"
            else
                printf "Cannot specify root twice (specified both '%s' and '%s')" "${ROOT}" "$1"
                exit 1
            fi
            ;;
    esac
    shift
done

Note that the variable FIND_RENAMES is either empty or has the whole, unchanged parameter. This means that I can just provide it as-is to git diff and you can automatically use all of the features from that command.

So, after we’ve already assigned each changed file it’s commit, we now also want to figure out if there are any renames according to git. To do this, we first need to find all unstaged files. Then we tell git that we intent to add them (using git add -N). Afterwards git will check whether it’s a renamed file or not. And we can ask whether it is by using git diff --name-status and filter for renames using --diff-filter=R.

We then simply save which file was renamed to what.

declare -A renamedFiles=()
if (( ${#FIND_RENAMES[@]} ));
then
    # first add all files indvidually as intent-to-add
    intentToAdd=$(git ls-files -o)
    for file in $intentToAdd;
    do
        git add -N "$file"
    done

# get all renames and save them into an associative array
    while IFS=$'\t' read -r origFile newFile;
    do
        renamedFiles["$origFile"]="$newFile"
    done < <(git diff --name-status --diff-filter=R "${FIND_RENAMES[@]}" | cut -f 2,3)

    # remove intent-to-add
    for file in $intentToAdd;
    do
        git reset -q -- "$file"
    done
fi

And when adding the files, we now also add all renamed files:

if [[ -v "renamedFiles[${file}]" ]];
then
    add_file "${renamedFiles[${file}]}"
fi

And that’s it.

Photo by Alex on Unsplash

Photo by Priscilla Du Preez on Unsplash

The Aho-Corasick algorithms allows you to find any amount of substrings and their position in a given search string. It does so in linear time. If the substrings are known beforehand, it is also possible to prepare them to later find matches in input strings faster.

Characteristics

• Inputs are a finite set of search strings (the “dictionary”) and the input string in which those dictionary strings are searched for.

• Output is a list of matched strings and their index in the input string. The list may include the same dictionary entries multiple times if they were found at multiple indices. The list is also sorted ascending by the index.

• Runtime complexity is O(L₁ + L₂ + M) without preparation or O(L₁ + M) if you prepare the dictionary beforehand. L₁ is the length of the input string; L₂ is the sum of the lengths of all search strings; and M is the amount of matches that a search string will produce. Preparation has a runtime complexity of O(L₂).

• Space complexity is O(L₂) in the worst case, but can be better if the dictionary strings share a lot of common prefixes.

• The Aho-Corasick algorithm was developed by Alfred V. Aho and Margaret J. Corasick in their paper “Efficient string matching: An aid to bibliographic search”

Principle

The basic idea behind the Aho-Corasick is to first convert the dictionary into a trie, where each node represents a prefix of a dictionary entry (or the entry itself). A trie is a special form of tree where all nodes represent strings and the children of each node contain the parent’s string plus an additional character at the end. The root node is the empty string (here represented by ε). Let’s look at an example.

Basic Trie

Image made by the author

All examples in this blog post will use a dictionary with the following dictionary:

• abba

• bb

• bar

• ar

• foobar

Those will result in the trie shown on the side (or top on mobile). The dictionary entry abba, for instance, was transformed into the four left-most nodes.

All nodes representing strings in the dictionary are also specifically marked so that we can recognize them when traversing over them. In the images, I marked them in green.

Using that trie we can now easily find out that the input string “bar” matches an entry in our dictionary by starting at the root and traversing over b to a to r.

Suffix Links

But looking at the input string “abar” we’d first traverse from a to b and then find out that we do not have a matching child. In that case we want to jump to the longest suffix of our current string (ab) that is in our tree: b. Note that the empty string is always the shortest suffix of every string. So if there is no longer substring in our tree, we’ll end up back at the root.

Since each node in the trie always has the same longest suffix, we can just remember those connections and include them in our initial tree creation. I’ve added those connections in the following image:

Image made by the author

Dictionary Suffix Links

The last problem that we have now is that we might miss some entries in our dictionary. Let’s take for example the input string “foobar”. We’ll successfully find the words foo and foobar since we directly traverse of their nodes. But we won’t find the dictionary strings bar and ar without an additional (the last) trick.

We add another link from each node to the longest suffix that is in the dictionary — the so-called “dictionary suffix links”. Now, whenever we traverse a node, we simply follow the dictionary suffix links (the green arrows in the image) to find all dictionary strings for that node.

Image made by the author

To summarize, each node now has three different kind of links to other nodes:

• Any amount of child links

• One suffix link to the node with the longest shared suffix

• At most one dictionary suffix link to the node with the longest shared suffix that also represents a dictionary entry

An Example

Now let’s try with the input string “aabbTfoobar”. This will require the use of all three links.

Warning: the trie is going to look pretty full now with the path drawn on it. I go through it step-by-step, so bear with me. You can also just try to do it yourself first.

Image made by the author

1. We start at ε and move to (a).

2. The node (a) doesn’t have a child with the string b, so we go back to the root and see if it has a matching child. It has. And we and up back at the same node.

3. We move to the child (ab).

4. We move to the child (abb). This node has a dictionary suffix link, so we follow it and find the dictionary entry bb.

5. The node doesn’t have a child for “T”, but it has a suffix link. So we follow that link to (bb). Since that node doesn’t have a fitting child either, we move to its suffix link (b). Again, no match and this time no suffix link, so we move to (ε). When (ε) has no fitting child, we just stay on it and still advance in the string.

6. We move to the child (f).

7. We move to the child (fo).

8. We move to the child (foo) and find the dictionary entry foo.

9. We move to the child (foob).

10. We move to the child (fooba).

11. We move to the child (fooobar) and find the dictionary entry foobar. Since the node also has a dictionary suffix link, we follow it and find the dictionary entry bar. Again, that node has a dictionary suffix link, so we find ar.

…and then we’re done. And we found all substrings in our dictionary.

Oh and if you prefer to listen to me instead, this post is based on a lightning talk I gave, where I (try to) explain them in 7 minutes.

What are Monads?

Monads are just classes that implement the following two methods:

• [of](https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html#of-T...-) (in explanations usually called unit or return) and

• [flatMap](https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html#flatMap-java.util.function.Function-) (usually called bind)

of should simply take some values and return a wrapper for it (the monad). flatMap then allows accessing those values by applying a function to all of them, taking the monads returned by those functions and combining (aka “flattening”) them into one again.

Using that, the simplest possible monad is the following:

public class Monad<T> {
    private T value;

    private Monad(T value) {
        this.value = value;
    }

    public static <T> Monad<T> of(T value) {
        return new Monad<>(value);
    }

    public<R> Monad<R> flatMap(Function<T, Monad<R>> f){
        return f.apply(value);
    }
}

So that’s it?

Mostly, but obviously you can’t just name the methods a certain way and have a monad. There are rules for how these two methods need to work together.

The good news is that if you implement those methods as described above (and as they are commonly understood), you’ll already fulfill all of them. But here they are anyways:

1. The of method is a left-identity for flatMap,

2. the of method is a right-identity for flatMap and

3. the flatMap method is associative.

Or, in code:

// using
Monad<V> m;
V x;
Function<V, Monad<V>> f;
Function<V, Monad<V>> g;

// rule 1: of is left-identity of flatMap
of(x).flatMap(f) .equals(f.apply(x))

// rule 2
m.flatMap(Monad::of) .equals(m)

// rule 3
m.flatMap(f).flatMap(h)
    .equals(m.flatMap(v -> g.apply(v).flatmap(h)))

Why should I care?

Now you know what monads are and how you can create one, but why is there even a name for it?

If you were using a heavily functional language, then this wouldn’t even really be a question since the tools and problems you’ll have when programming functionally will likely naturally result in you creating some monads¹. That’s where monads are from originally.

That being said, they can also be tremendously useful outside of those languages and in fact many new APIs feature monads.

Include (error) states in your domain

The best APIs try to stop you from making mistakes. One of the ways that this is done is explicitly including the error state in its return values. When multiple function calls in a row could return an error, this also has the added bonus of making the resulting code prettier.

Let’s look at an example using Optional:

public Optional<Integer> doSomething(Stream<Integer> stream) {
    return stream
        .findFirst()
        .flatMap(this::integerHalf)
        .flatMap(v -> Optional.of(v*5));
}

public Optional<Integer> integerHalf(Integer i) {
    if (i%2 == 0) {
        return Optional.of(i/2);
    } else {
        return Optional.empty();
    }
}

In this example, we not only had the option to return an “error” at any time, but afterwards we don’t immediately have to check for it. Instead this can be done at a later point.

Monads can also be used to take care of non-error states. This is often used in collections or asynchronous programming (see [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)), where it also prevents callback-hell.

Allow the use of more generic functions

Take the above function integerHalf for example: We can use this on plain integers and also on any monad like Optional or Stream using the flatMap method.

This ease of access to the underlying information while not leaving the domain of the Monad can create amazing APIs that prevent many errors.

Do you know some monads?

I’ve already mentioned the three most common monads in Java:

• Optional,

• Stream and

• CompletableFuture

but I’m sure you’ve encountered a few more already. Leave a comment if you know another good example.

Further links

• Maybe the best explanation of the theory behind monads (and functors and applicatives) — with pictures!

• ¹A great explanation of why monads naturally arise when programming functionally

• My 7-minute lightning talk about this topic

Accurate image of a monad (Photo by: Nicole De Khors)