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)
Ktlint-suppression rule¶
The ktlint-disable and ktlint-enable directives are no longer supported as of ktlint version 0.50.0. This rule migrates the directives to Suppress or SuppressWarnings annotations.
Identifiers in the @Suppress and @SuppressWarnings annotations to suppress ktlint rules are checked for validity and autocorrected when possible.
/* ktlint-disable standard:no-wildcard-imports */
class FooBar {
val foo = "some longggggggggggggggggggg text" // ktlint-disable standard:max-line-length
fun bar() =
listOf(
/* ktlint-disable standard:no-multi-spaces */
"1 One",
"10 Ten",
"100 Hundred",
/* ktlint-enable standard:no-multi-spaces */
)
}
Rule id: ktlint-suppression (standard rule set)
Note
This rule can not be disabled in the .editorconfig.
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)