Standard rules
Annotation formatting¶
Multiple annotations should be on a separate line than the annotated declaration; annotations with parameters should each be on separate lines; annotations should be followed by a space
// A single annotation (without parameters) is allowed on same line as annotated construct
@FunctionalInterface class FooBar {
@JvmField var foo: String
@Test fun bar() {}
}
// A class or function parameter may have a single annotation with parameter(s) on the same line
class Foo(@Path("fooId") val fooId: String)
class Bar(
@NotNull("fooId") val fooId: String,
@NotNull("bar") bar: String
)
// Multiple annotations (without parameters) are allowed on the same line
@Foo @Bar
class FooBar {
@Foo @Bar
var foo: String
@Foo @Bar
fun bar() {}
}
// An array of annotations (without parameters) is allowed on same line as annotated construct
@[Foo Bar] class FooBar2 {
@[Foo Bar] var foo: String
@[Foo Bar] fun bar() {}
}
// An annotation with parameter(s) is not allowed on same line as annotated construct
@Suppress("Unused") class FooBar {
@Suppress("Unused") var foo: String
@Suppress("Unused") fun bar() {}
}
// Multiple annotation on same line as annotated construct are not allowed
@Foo @Bar class FooBar {
@Foo @Bar var foo: String
@Foo @Bar fun bar() {}
}
Rule-id: annotation
(standard
rule set)
Argument list wrapping¶
All arguments should be on the same line, or every argument should be on a separate line.
Rule-id: argument-list-wrapping
(standard
rule set)
Block comment initial star alignment¶
Lines in a block comment which (exclusive the indentation) start with a *
should have this *
aligned with the *
in the opening of the block comment.
Rule id: block-comment-initial-star-alignment
(standard
rule set)
Chain wrapping¶
When wrapping chained calls .
, ?.
and ?:
should be placed on the next line
Rule id: chain-wrapping
(standard
rule set)
Class/object naming¶
Enforce naming of class.
Note
Functions in files which import a class from package org.junit.jupiter.api
are considered to be test functions and are allowed to have a name specified between backticks and do not need to adhere to the normal naming convention. Although, the Kotlin coding conventions does not allow this explicitly for class identifiers, ktlint
does allow it.
This rule can also be suppressed with the IntelliJ IDEA inspection suppression ClassName
.
Rule id: class-naming
(standard
rule set)
Enum entry¶
Enum entry names should be uppercase underscore-separated or upper camel-case separated.
Rule id: enum-entry-name-case
(standard
rule set)
File name¶
A file containing only one visible (e.g. non-private) class, and visible declarations related to that class only, should be named according to that element. The same applies if the file does not contain a visible class but exactly one type alias or one object declaration. Otherwise, the PascalCase notation should be used.
Rule id: filename
(standard
rule set)
Final newline¶
Ensures consistent usage of a newline at the end of each file.
This rule can be configured with .editorconfig
property insert_final_newline
.
Rule id: final-newline
(standard
rule set)
Import ordering¶
Ensures that imports are ordered consistently (see Import Layouts for configuration).
Rule id: import-ordering
(standard
rule set)
Indentation¶
Indentation formatting - respects .editorconfig
indent_size
with no continuation indent (see EditorConfig section for more).
Note
This rule handles indentation for many different language constructs which can not be summarized with a few examples. See the unit tests for more details.
Rule id: indent
(standard
rule set)
Max line length¶
Ensures that lines do not exceed the given length of .editorconfig
property max_line_length
(see EditorConfig section for more). This rule does not apply in a number of situations. For example, in the case a line exceeds the maximum line length due to a comment that disables ktlint rules then that comment is being ignored when validating the length of the line. The .editorconfig
property ktlint_ignore_back_ticked_identifier
can be set to ignore identifiers which are enclosed in backticks, which for example is very useful when you want to allow longer names for unit tests.
// Assume that the last allowed character is
// at the X character on the right X
// Lines below are accepted although the max
// line length is exceeded.
package com.toooooooooooooooooooooooooooo.long
import com.tooooooooooooooooooooooooooooo.long
val foo =
"""
fooooooooooooooooooooooooooooooooooooooooo
"""
@Test
fun `Test description which is toooooooooooo long`() {
}
Rule id: max-line-length
(standard
rule set)
Modifier order¶
Consistent order of modifiers
Rule id: modifier-order
(standard
rule set)
Multiline if-else¶
Braces required for multiline if/else statements.
Rule id: multiline-if-else
(standard
rule set)
No blank lines before }
¶
No blank lines before }
.
Rule id: no-blank-line-before-rbrace
(standard
rule set)
No blank lines in chained method calls¶
Rule id: no-blank-lines-in-chained-method-calls
(standard
rule set)
No consecutive blank lines¶
Rule id: no-consecutive-blank-lines
(standard
rule set)
No empty ({}
) class bodies¶
Rule id: no-empty-class-body
(standard
rule set)
No leading empty lines in method blocks¶
Rule id: no-empty-first-line-in-method-block
(standard
rule set)
No line break after else¶
Disallows line breaks after the else keyword if that could lead to confusion, for example:
Rule id: no-line-break-after-else
(standard
rule set)
No line break before assignment¶
When a line is broken at an assignment (=
) operator the break comes after the symbol.
Rule id: no-line-break-before-assignment
(standard
rule set)
No multi spaces¶
Except in indentation and in KDoc's it is not allowed to have multiple consecutive spaces.
Rule id: no-multi-spaces
(standard
rule set)
No semicolons¶
No semicolons (unless used to separate multiple statements on the same line).
Rule id: no-semi
(standard
rule set)
No trailing whitespaces¶
Rule id: no-trailing-spaces
(standard
rule set)
No Unit
as return type¶
The Unit
type is not allowed as return type of a function.
returns (fun fn {}
instead of fun fn: Unit {}
)
Rule id: no-unit-return
(standard
rule set)
No unused imports¶
Warning
This rule is not able to detect all unused imports as mentioned in this issue comment.
Rule id: no-unused-imports
(standard
rule set)
No wildcard imports¶
No wildcard imports except imports listed in .editorconfig
property ij_kotlin_packages_to_use_import_on_demand
.
Warning
In case property ij_kotlin_packages_to_use_import_on_demand
is not explicitly set, it allows wildcards imports like java.util.*
by default to keep in sync with IntelliJ IDEA behavior. To disallow all wildcard imports, add property below to your .editorconfig
:
Rule id: no-wildcard-imports
(standard
rule set)
Package name¶
Validates that the package name matches the regular expression [a-z][a-zA-Z\d]*(\.[a-z][a-zA-Z\d]*)*
.
Rule id: package-name
(standard
rule set)
Parameter list wrapping¶
When class/function signature doesn't fit on a single line, each parameter must be on a separate line
Rule id: parameter-list-wrapping
(standard
rule set)
Parameter wrapping¶
When a function or class parameter doesn't fit on a single line, wrap the type or value to a separate line
Rule id: parameter-wrapping
(standard
rule set)
Property wrapping¶
When a property doesn't fit on a single line, wrap the type or value to a separate line
Rule id: property-wrapping
(standard
rule set)
String template¶
Consistent string templates ($v
instead of ${v}
, ${p.v}
instead of ${p.v.toString()}
)
Rule id: string-template
(standard
rule set)
Trailing comma on call site¶
Consistent removal (default) or adding of trailing commas on call site.
Important
KtLint uses the IntelliJ IDEA .editorconfig
property ij_kotlin_allow_trailing_comma_on_call_site
to configure the rule. When this property is enabled, KtLint enforces the usage of the trailing comma at call site while IntelliJ IDEA default formatter only allows to use the trailing comma but leaves it to the developer's discretion to actually use it (or not). KtLint values consistent formatting more than a per-situation decision.
Note
In KtLint 0.48.x the default value for using the trailing comma on call site has been changed to true
except when codestyle android
is used.
Although the Kotlin coding conventions leaves it to the developer's discretion to use trailing commas on the call site, it also states that usage of trailing commas has several benefits:
- It makes version-control diffs cleaner – as all the focus is on the changed value.
- It makes it easy to add and reorder elements – there is no need to add or delete the comma if you manipulate elements.
- It simplifies code generation, for example, for object initializers. The last element can also have a comma.
Note
Trailing comma on call site is automatically disabled if the Wrapping rule (or, before version 0.45.0
, the Indentation rule) is disabled or not loaded. Because it cannot provide proper formatting with unwrapped calls. (see dependencies).
Rule id: trailing-comma-on-call-site
(standard
rule set)
Trailing comma on declaration site¶
Consistent removal (default) or adding of trailing commas on declaration site.
Important
KtLint uses the IntelliJ IDEA .editorconfig
property ij_kotlin_allow_trailing_comma
to configure the rule. When this property is enabled, KtLint enforces the usage of the trailing comma at declaration site while IntelliJ IDEA default formatter only allows to use the trailing comma but leaves it to the developer's discretion to actually use it (or not). KtLint values consistent formatting more than a per-situation decision.
Note
In KtLint 0.48.x the default value for using the trailing comma on declaration site has been changed to true
except when codestyle android
is used.
The Kotlin coding conventions encourages the usage of trailing commas on the declaration site, but leaves it to the developer's discretion to use trailing commas on the call site. But next to this, it also states that usage of trailing commas has several benefits:
- It makes version-control diffs cleaner – as all the focus is on the changed value.
- It makes it easy to add and reorder elements – there is no need to add or delete the comma if you manipulate elements.
- It simplifies code generation, for example, for object initializers. The last element can also have a comma.
Note
Trailing comma on declaration site is automatically disabled if the Wrapping rule (or, before version 0.45.0
, the Indentation rule) is disabled or not loaded. Because it cannot provide proper formatting with unwrapped declarations. (see dependencies).
Rule id: trailing-comma-on-declaration-site
(standard
rule set)
Unnecessary parenthesis before trailing lambda¶
An empty parentheses block before a lambda is redundant.
Rule id: unnecessary-parentheses-before-trailing-lambda
(standard
rule set)
Wrapping¶
Wrapping¶
Inserts missing newlines (for example between parentheses of a multi-line function call).
Rule id: wrapping
(standard
rule set)
Comment wrapping¶
A block comment should start and end on a line that does not contain any other element.
Rule id: comment-wrapping
(standard
rule set)
Spacing¶
Angle bracket spacing¶
No spaces around angle brackets when used for typing.
Rule id: spacing-around-angle-brackets
(standard
rule set)
Annotation spacing¶
Annotations should be separated by a single line break.
Rule id: annotation-spacing
(standard
rule set)
Blank line between declarations with annotations¶
Declarations with annotations should be separated by a blank line.
Rule id: spacing-between-declarations-with-annotations
(standard
rule set)
Blank line between declaration with comments¶
Declarations with comments should be separated by a blank line.
Rule id: spacing-between-declarations-with-comments
(standard
rule set)
Colon spacing¶
Consistent spacing around colon.
Rule id: colon-spacing
(standard
rule set)
Comma spacing¶
Consistent spacing around comma.
Rule id: comma-spacing
(standard
rule set)
Comment spacing¶
The end of line comment sign //
should be preceded and followed by exactly a space.
Rule id: comment-spacing
(standard
rule set)
Curly spacing¶
Consistent spacing around curly braces.
Rule id: curly-spacing
(standard
rule set)
Dot spacing¶
Consistent spacing around dots.
Rule id: dot-spacing
(standard
rule set)
Double colon spacing¶
No spaces around ::
.
Rule id: double-colon-spacing
(standard
rule set)
Function return type spacing¶
Consistent spacing around the function return type.
Rule id: function-return-type-spacing
(standard
rule set)
Function start of body spacing¶
Consistent spacing before start of function body.
Rule id: function-start-of-body-spacing
(standard
rule set)
Function type reference spacing¶
Consistent spacing in the type reference before a function.
Rule id: function-type-reference-spacing
(standard
rule set)
Fun keyword spacing¶
Consistent spacing after the fun keyword.
Rule id: fun-keyword-spacing
(standard
rule set)
Kdoc wrapping¶
A KDoc comment should start and end on a line that does not contain any other element.
Rule id: kdoc-wrapping
(standard
rule set)
Keyword spacing¶
Consistent spacing around keywords.
Rule id: keyword-spacing
(standard
rule set)
Modifier list spacing¶
Consistent spacing between modifiers in and after the last modifier in a modifier list.
Rule id: modifier-list-spacing
(standard
rule set)
Nullable type spacing¶
No spaces in a nullable type.
Rule id: nullable-type-spacing
(standard
rule set)
Operator spacing¶
Consistent spacing around operators.
Rule id: op-spacing
(standard
rule set)
Parenthesis spacing¶
Consistent spacing around parenthesis.
Rule id: paren-spacing
(standard
rule set)
Range spacing¶
Consistent spacing around range operators.
Rule id: range-spacing
(standard
rule set)
Spacing between function name and opening parenthesis¶
Consistent spacing between function name and opening parenthesis.
Rule id: spacing-between-function-name-and-opening-parenthesis
(standard
rule set)
Unary operator spacing¶
No spaces around unary operators.
Rule id: unary-op-spacing
(standard
rule set)