How to Keep Kotlin Formatting Consistent

A pull request comes back with eleven comments. Two are about the logic. Nine are about where the braces go, whether the chained call should break, and why one file uses two-space indentation.

None of those nine needed a human. They are exactly the class of question a formatter settles, and every minute spent on them in review is a minute not spent on the two that mattered.

Why formatting belongs in the build

A shared style has one real benefit: it removes a category of decision. Nobody chooses where the brace goes because the tool has already decided, and nobody comments on it in review because there is nothing to comment on.

That only works if the formatting is enforced rather than encouraged. A style guide everyone agrees with and nobody runs produces a codebase where each file matches whoever last touched it.

Enforcement means a check in continuous integration that fails on unformatted code, and ideally a pre-commit hook so it never reaches CI. Tools like ktlint and detekt exist for exactly this and integrate with Gradle in a few lines.

The formatter itself is the easy part. Deciding to enforce it is the decision that matters.

What the conventions actually specify

The official Kotlin coding conventions cover more than indentation, and the parts that produce the most review noise are:

Indentation of four spaces, not tabs, and not two.

Line length, conventionally around 100 to 120 characters. Beyond that, chained calls and long parameter lists break one per line.

Trailing commas, which are permitted and reduce diff noise — adding a parameter touches one line instead of two.

Expression bodies for single-expression functions, using = rather than a block with a return.

Import ordering, which is trivial and generates a surprising number of merge conflicts when it is inconsistent.

Formatting never changes behaviour

Worth being explicit, because it is what makes automated formatting safe to apply across a whole repository at once.

A formatter alters whitespace and line breaks. It does not reorder statements, change expressions, add or remove imports that affect resolution, or touch semantics in any way. Running it over a thousand files produces a large diff and an identical program.

The one practical caution is that a repository-wide reformat makes git blame less useful. Most teams handle this by committing the reformat on its own and adding that commit to a blame-ignore file, which git supports directly.

Configure the IDE from the repository

Per-developer editor settings are how a formatted repository becomes an unformatted one.

Most editors read a configuration file from the project root — an EditorConfig file at minimum, and IDE-specific settings that can be committed alongside. Those set indentation, line endings and trailing whitespace behaviour for anyone who opens the project.

Without them, each developer’s global preferences apply, and a file touched by three people acquires three styles. The CI check then fails on a change that had nothing to do with formatting.

Committing the configuration takes minutes and means new team members are correct on their first commit rather than after their first failed build.

Common mistakes to avoid

• Agreeing a style and not enforcing it, which produces a codebase where every file reflects its last author.
• Reformatting a repository in the same commit as a behavioural change, which makes the real change impossible to review.
• Leaving formatting comments in review when a tool could settle them.
• Configuring the IDE formatter per developer instead of committing shared settings to the repository.
• Setting a line length so long that wrapping never happens, which produces lines nobody can read in a side-by-side diff.

How to do it with Kotlin Code Formatter

The Kotlin Code Formatter applies the official conventions to pasted code.

1. Paste the Kotlin source — a file, a class, or a single function.
2. Set indentation and maximum line length to match your project.
3. Copy the formatted output back.
4. For anything ongoing, add ktlint or an equivalent to the build so the same rules run automatically.

The Kotlin coding conventions are the authoritative reference. Other developer tools are in the tools directory.

Frequently asked questions

Does this match what ktlint produces?

It follows the same official conventions ktlint is built around. For a project already using ktlint, run that in the build — a formatter in the pipeline beats one anyone can forget to use.

Can formatting break my code?

No. It only changes whitespace and line breaks. Behaviour, imports and semantics are untouched, which is what makes a repository-wide reformat safe.

Should the whole repository be reformatted at once?

Usually yes, in a single commit that does nothing else, with that commit added to a blame-ignore file. Formatting gradually leaves the codebase inconsistent for months.

Final thought

Put the formatter in the build, not in the review. Nine comments about brace placement is nine comments nobody had to write.

Try the free Kotlin Code Formatter