Introduction

Discover what the Primer is, if it’s something you can benefit from, what you can/can’t expect from it and how to best go about reading it.

— — — — — — — — — — — — — — —

THE CURRENT VERSION OF THIS ARTICLE IS PUBLISHED HERE.

— — — — — — — — — — — — — — —

The Kotlin Primer is an opinionated guide to the Kotlin language, which is indented to help facilitate Kotlin adoption inside Java-centric organizations. It was originally written as an organizational learning resource for Etnetera a.s., and I would like to express my sincere gratitude for their support.

The Kotlin Primer was designed to be accessible to developers of all seniorities and has been successfully tested in the real world, with real people working real jobs in a real business.

Is the Primer for you?

You can benefit from reading the Primer if:

You are a Java developer of any seniority with no experience in Kotlin, and want to learn the language.

The Primer starts from the basics and makes absolutely no assumptions about existing knowledge, beyond basic familiarity with Java. You will learn not only the mechanics of the language, but also how to write idiomatic Kotlin in a consistent way, which features to use in which situations, and why. You will also learn design methodologies that promote maintainability, and are applicable outside of Kotlin as well.

You already have experience with Kotlin.

There are three reasons for this.

The first reason is that the Primer thoroughly analyses the “soft” aspects of writing in Kotlin. For example, you probably know what the individual scope functions are, but do you know when you should use which? Can you give logical and consistent reasons for those choices? Are those reasons motivated by a specific purpose, or are they ad hoc (e.g. “because that’s what the docs say”)? Regardless of which answers you gave, being confronted with the approach taken in the Primer can potentially widen your perspective.

The second reason is that part of the Primer’s value lies in subjects that are not specific to Kotlin. For example, the Primer’s treatment of generic variance is, to my knowledge, somewhat unique. Some subjects, such as functional domain-modeling, pertain to programming methodologies that directly promote maintainability, and I firmly believes that programmers of any experience level can benefit from being exposed to them.

The third reason is that the Primer includes curated links to quality materials elsewhere, collected through hundreds of hours of sifting through online material. In a few cases, the articles are so good that it is difficult to overstate their quality — those are usually mentioned in a visibly enthusiastic manner.

You are pressed for time.

The Primer is tailored to the environment of organizations like Etnetera, where revenue is generated by billing time — time literally is money. As a consequence, the Primer only discusses things where it has something of value to say. It starts out fast, since language beginnings are straightforward, but slows down considerably as it progresses to novel material. It does not waste time where it is not needed and refers you to the documentation whenever its contents are sufficient, or gives TL;DR-style rundowns.

The amount of time it takes to complete the Primer cover-to-cover is typically 2–3 MDs, depending on seniority and familiarity with Kotlin.

You are interested not only in theory, but also in practical aspects.

As was mentioned, the Primer is, in a sense, a compilation of my experience using Kotlin. It is not a generic textbook, but also imparts opinions based on real-world experience. These opinions, and the reasons for them, are always motivated, thoroughly explained, and unapologetic, even when this means being in conflict with the official documentation.

You like a hands on, no-nonsense approach.

The Primer uses embedded Kotlin Playground code to provide interactive demonstrations for all the material, which can be edited and run directly from the article page. Here is an example:

Additionally, every article introducing a new concept includes exercises that can be run and completed directly on the page of the article. The exercises are designed to really drive home how things work, validated by tests, and often require some effort to solve.

The Primer does not waste time with trivial exercises that serve only to frustrate the intelligent reader. It has faith that you can indeed write a function that sums two integers, and doesn’t really see the need for you to prove it. It is for this reason that there are no exercises until the article on Nullability.

What you won’t find in the Primer

Subjects outside the JVM

The Primer is focused solely on the JVM.

Coroutines

The Primer is a publication which strives to provide a certain level of quality to its readers. It is not satisfied with explanations that involve hand waving, and expects to be able to dissect every issue down to the fundamental level necessary to truly understand a given topic.

A direct prerequisite for this is a satisfactory amount of practical experience, not only with the topic, but also with learning the topic. If there is any quality to the Primer, it is a consequence of undertaking many paths through the material, from those that are readily available elsewhere, to those that are a result of experimentation, introspection, or challenges one puts themselves to, and then looking back and picking the one which is deemed most satisfactory.

I don’t yet feel that I have reached this threshold with coroutines, and I currently don’t feel confident the material would live up to the standards of quality to which this publication aspires to.

Certain newer features

The Primer was written during the year 2021, based on experience gathered during previous years. Therefore, certain newer features that have since arrived are not covered in these materials, for reasons similar to those stated above. I will cover these subjects once I am satisfied with the degree to which I understand them.

Political correctness

Though used sparingly, there are times where “fucking” and “bullshit” are the only words that truly capture the essence of a situation.

How to read the Primer

Unless you are an avid reader, it is not necessary to read these materials from start to finish. You should instead browse through and concentrate on understanding two key things: 1) what features Kotlin offers, and 2) the problems they solve. Of these two, the latter is the most important — awareness of a problem will cause you to recognize it when it arises, and look for a solution. This will quickly lead you to the information you need.

I generally recommend against attempting to memorize all the details on the first go. Unless it’s something important, it’s usually better to just make a mental note that feature X is there for certain situations, and when you encounter these situations in real life, come back and read the section on feature X.

To help you make decisions on what to concentrate on, each article in the Primer is tagged with the type of information included. The article heading will be tagged with all tags of subheadings, and each subheading might have its own set of tags.

These tags are:

FYI

• Often similar to what is available in Java, or not of large significance, and trivial to understand
• If you’ve never or only briefly used Kotlin, just quickly scroll through and be aware of what it is. No need to invest lots of time
• If you’ve already used Kotlin more than a few times, you can probably skip it

FYI++

• Basically the same as FYI, but also includes something extra that you might find interesting — a new concept, interpretation, link to external materials etc.

KOTLIN FEATURE

• Important and different from what’s available in Java, but shouldn’t be hard to understand
• If you’ve never or only briefly used Kotlin, read through carefully and make sure you understand the principles of the feature and most importantly when you should use it. Then come back and read it again when you need it.
• If you’ve already used Kotlin more than a few times, just quickly scroll through and check if maybe there’s some aspect you didn’t know of

FUNDAMENTAL CONCEPT

• Completely different from what’s available in Java and also may require a new style of thinking to understand and use effectively
• You should invest the time and read through this, regardless of your seniority level. There is a distinct possibility you will learn something new, be confronted with a novel interpretation, or discover motivation for using it in a particular manner

EXERCISE

• Contains exercises
• Exercises are included for every FUNDAMENTAL CONCEPT and for most of the KOTLIN FEATURE, but not for the rest — I see no point in “Create a Dog class that..." nonsense.
• When an exercise is there, it’s there for a reason — do it.

Material categorization

Introduction

• Describes basic language syntax and the type system
• Pay special attention to when, string templates, nullability and higher-order functions/lambdas. Understand that almost everything is an expression
• I recommend reading the “expanded” version of types, but that can be left for later
• Make mental notes about ranges, tailrec, inline and vararg

Classes — What we know from Java

• Lengthy section on the aspects of classes that differ only slightly from what is available in Java
• Mainly included as a reference
• Be sure to understand the fundamentals, as they are different from Java, especially the primary constructor and properties
• I recommend reading the section on variance — even if you understand the concepts, it might give you a different point of view
• The rest of the section on generics might also warrant closer attention
• Other than that, just sort of fly through quickly, there are almost no exercises

Classes — What is different

• Pay special attention to reified type parameters, data classes, sealed hierarchies, inline classes, objects and delegation — especially the last one can take time
• Dedicate time and energy to really understand the concept of modeling error states using sealed class hierarchies, and use it. It will make you a better programmer, and your code easier to maintain.
• Make mental notes of enums, infix functions, operators, type aliases and functional (SAM) interfaces

Extension functions

• Read the whole thing. No exceptions, everything is important

Standard library

• Pay special attention to Programming with Result — along with modeling errors states using classes, discussed in Classes — What is different, this is among the most important things you can learn from the Primer.
• Read the lesson on functional programming and why you should use it, why we needs Sequences, and pausing functions
• Other than that, almost no theory, just a demonstration of the stdlib
• Make mental note of everything

Jump to the Table of Contents or continue to the Preface.