How to Comply with the Kotlin Style Guide Using ktlint on Android

Ready to build better conversations?

Simple to set up. Easy to use. Powerful integrations.

Get free access

What is ktlint?

ktlint is a static code analysis tool for Kotlin and Java programming languages. It validates code for compliance with coding standards such as the Kotlin Style Guide and assists developers in writing clean and consistent code. Developers can use ktlint to easily identify and fix style issues in their codebase, resulting in fewer bugs and a more maintainable codebase overall.

In this guide, we will see how to setup ktlint and use it in a project. Then we see how we can use it through CI/CD to validate code formatting.

Setup

In order to use ktlint in an Android project, we will use Jonathan Leitschuh's ktlint Gradle plugin which wraps the original ktlint and creates Gradle tasks that run ktlint checks and can even directly apply style corrections on your codebase.

First, add the plugin to your project's build script file build.gradle(.kts)

Optionally, add the following to apply the plugin to all project modules

After running a Gradle Project Sync, ktlint should now have been added to your project!

Usage

You are now able to run gradle tasks such as the following:

• ktlintCheck will run a check through the modules where ktlint is applied.
  It will succeed when there is no formatting issue, and fail when there is one or more.

• ktlintFormat on top of running a check, will apply code styling rules directly to make your code compliant. Note that some issues cannot be solved automatically and will require manual editing.

• ktlintGenerateBaseline will create a baseline.xml file in each of the modules where ktlint is applied. This baseline is used when running a check to tell ktlint to ignore the issues it contains.
  It is useful if you want to enforce the code style only on new code for instance.

The steps and commands I have mentioned are the one we currently make use of at Aircall, but more configuration changes can be done to the plugin if you find the need to, so I invite you to read the documentation.

Integration with the CI/CD

(The rest of this guide assumes you are using GitLab CI/CD, but the principles should stay the same for other platforms, so stick around!)

Adding a simple step

You may want to integrate the ktlintCheck within your pipelines in order to make sure your new code complies with the style guide before being delivered.
In order to do this, simply create a job (in a new or in your existing .yml files) that contains the following for the script keyword:

--continue makes it possible to not stop at the first issue encountered during the check.

You can then add it to the stage of your choice, and it will be part of your pipelines and perform a style check.

This is a first step to keep your code quality in check, but it can be cumbersome to go and read the job’s logs directly from the pipeline. This is especially true if you have a big project and the logs go over the maximum amount of lines that can be displayed from GitLab’s page.

Leveraging GitLab’s Code Quality

A second step is to make use of GitLab’s Code Quality feature that enables you to see what is wrong with the new version of the code at a glance.

Example of a code quality result from GitLab

This is a much more convenient way to look at the issues, but it requires some work, as we need to merge ktlint’s many reports files in the Checkstyle format (xml) and convert them to the Code Quality format (json).

By default, ktlint creates reports in the root project’s build/reports/ktlint/merge folder where each module contains has its own folder containing its reports after a check has been run.

We will create a gradle task that we can run right after ktlintCheck to perform the conversion.
In order to do so, simply register a new task in your build.gradle(.kts) file like this:

Create the Kotlin file that corresponds to this Task, that will perform the merge and conversion.

Now, add the task to the job you created earlier. You also need to add the code quality report as an artifact so that it is available for GitLab to display its results.

A Code Quality will now be generated after the check is performed, and the results will conveniently be displayed right from the relevant MR’s overview tab.

Our experience

Using ktlint helps us ensure that our code is compliant with the Kotlin Style Guide and is more consistent across the codebase. It also makes it quick and easy to identify and fix style issues.

Having such a tool can save a lot of time and effort over the long run. It also makes it possible to catch mistakes before they make it to the code review process, which makes the workflow more efficient.

One challenge we could face is if there are reported issues that we don’t agree with, which has not occurred so far. If that were to happen, we would have to configure the ktlint rules to fit the team’s coding conventions.

Thank you for following this guide. I hope it will help you improve your code formatting and your project’s workflow.
Finally, I wish to thank my colleagues, especially Olivier Buiron for his precious help crafting the task to convert reports into a code quality file.

Published on January 12, 2023.