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,
@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)
Blank line before declarations¶
Requires a blank line before any class or function declaration. No blank line is required between the class signature and the first declaration in the class. In a similar way, a blank line is required before any list of top level or class properties. No blank line is required before local properties or between consecutive properties.
Rule id: blank-line-before-declaration
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
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)
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.
Configuration setting | ktlint_official | intellij_idea | android_studio |
---|---|---|---|
insert_final_newline |
true |
true |
true |
Rule id: final-newline
(standard
rule set)
Function signature¶
Rewrites the function signature to a single line when possible (e.g. when not exceeding the max_line_length
property) or a multiline signature otherwise.
Note
Wrapping of parameters is also influenced by the parameter-list-wrapping
rule.
// Assume that the last allowed character is
// at the X character on the right X
fun foooooooo(
a: Any,
b: Any,
c: Any,
): String {
// body
}
// Assume that the last allowed character is
// at the X character on the right X
fun bar(a: Any, b: Any, c: Any): String {
// body
}
// When wrapping of body is set to 'default'.
// Assume that the last allowed character is
// at the X character on the right X
fun f(a: Any, b: Any): String = "some-result"
.uppercase()
// When wrapping of body is set to 'multiline'
// or 'always'.
// Assume that the last allowed character is
// at the X character on the right X
fun f(a: Any, b: Any): String =
"some-result"
.uppercase()
// Assume that the last allowed character is
// at the X character on the right X
fun foooooooo(a: Any, b: Any, c: Any): String {
// body
}
// Assume that the last allowed character is
// at the X character on the right X
fun bar(
a: Any,
b: Any,
c: Any
): String {
// body
}
// When wrapping of body is set to 'default'.
// Assume that the last allowed character is
// at the X character on the right X
fun f(a: Any, b: Any): String =
"some-result"
.uppercase()
// When wrapping of body is set to 'multiline'
// or 'always'.
// Assume that the last allowed character is
// at the X character on the right X
fun f(a: Any, b: Any): String = "some-result"
.uppercase()
Configuration setting | ktlint_official | intellij_idea | android_studio |
---|---|---|---|
ktlint_function_signature_body_expression_wrapping Determines how to wrap the body of function in case it is an expression. Use default to wrap the body expression only when the first line of the expression does not fit on the same line as the function signature. Use multiline to force wrapping of body expressions that consists of multiple lines. Use always to force wrapping of body expression always. |
multiline |
default |
default |
ktlint_function_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than Forces a multiline function signature in case the function contains the specified minimum number of parameters even in case the function signature would fit on a single line. Use value unset (default) to disable this setting. |
2 | unset |
unset |
When ktlint_function_signature_body_expression_wrapping
is set to default
, the first line of a body expression is appended to the function signature as long as the max line length is not exceeded.
// Given that the function signature has to be written as a single line
// function signature and that the function has a multiline body expression
fun someFunction(a: Any, b: Any): String = "some-result"
.uppercase()
// Given that the function signature has to be written as a multiline
// function signature and that the function has a multiline body expression
fun someFunction(
a: Any,
b: Any
): String = "some-result"
.uppercase()
When ktlint_function_signature_body_expression_wrapping
is set to multiline
, the body expression starts on a separate line in case it is a multiline expression. A single line body expression is wrapped only when it does not fit on the same line as the function signature.
// Given that the function signature has to be written as a single line
// function signature and that the function has a single line body expression
// that fits on the same line as the function signature.
fun someFunction(a: Any, b: Any): String = "some-result".uppercase()
// Given that the function signature has to be written as a multiline
// function signature and that the function has a single line body expression
// that fits on the same line as the function signature.
fun someFunction(
a: Any,
b: Any
): String = "some-result".uppercase()
// Given that the function signature has to be written as a single line
// function signature and that the function has a multiline body expression
fun someFunction(a: Any, b: Any): String =
"some-result"
.uppercase()
// Given that the function signature has to be written as a multiline
// function signature and that the function has a multiline body expression
fun someFunction(
a: Any,
b: Any
): String =
"some-result"
.uppercase()
When ktlint_function_signature_body_expression_wrapping
is set to always
the body expression is always wrapped to a separate line.
// Given that the function signature has to be written as a single line
// function signature and that the function has a single line body expression
fun someFunction(a: Any, b: Any): String =
"some-result".uppercase()
// Given that the function signature has to be written as a multiline
// function signature and that the function has a multiline body expression
fun functionWithAVeryLongName(
a: Any,
b: Any
): String =
"some-result"
.uppercase()
Rule id: function-signature
(standard
rule set)
If else bracing¶
If at least one branch of an if-else statement or an if-else-if statement is wrapped between curly braces then all branches should be wrapped between braces.
Rule id: if-else-bracing
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
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.
Configuration setting | ktlint_official | intellij_idea | android_studio |
---|---|---|---|
indent_size The size of an indentation level when indent_style is set to space . Use value unset to ignore indentation. |
4 | 4 | 4 |
indent_style Style of indentation. Set this value to space or tab . |
space |
space |
space |
Rule id: indent
(standard
rule set)
Naming¶
Class naming¶
Enforce naming of class and objects.
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)
Function naming¶
Enforce naming of function.
Configuration setting | ktlint_official | intellij_idea | android_studio |
---|---|---|---|
ktlint_function_naming_ignore_when_annotated_with Ignore functions that are annotated with values in this setting. This value is a comma separated list of names without the '@' prefix. |
unset |
unset |
unset |
Note
When using Compose, you might want to configure the function-naming
rule with .editorconfig
property ktlint_function_naming_ignore_when_annotated_with=Composable
. Furthermore, you can use a dedicated ktlint ruleset like Compose Rules for checking naming conventions for Composable functions.
Note
Functions in files which import a class from package io.kotest
, junit.framework
, kotlin.test
, org.junit
, or org.testng
are considered to be test functions. Functions in such classes are allowed to have underscores in the name. Also, function names enclosed between backticks do not need to adhere to the normal naming convention.
This rule can also be suppressed with the IntelliJ IDEA inspection suppression FunctionName
.
Rule id: function-naming
(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)
Property naming¶
Enforce naming of property.
Note
This rule can not reliably detect all situations in which incorrect property naming is used. So it only detects in which it is certain that naming is incorrect.
val foo1 = Foo() // In case developer want to communicate that Foo is mutable
val FOO1 = Foo() // In case developer want to communicate that Foo is deeply immutable
const val FOO_BAR = "FOO-BAR" // By definition deeply immutable
var foo2: Foo = Foo() // By definition not immutable
class Bar {
val foo1 = "foo1" // Class properties always start with lowercase, const is not allowed
const val FOO_BAR = "FOO-BAR" // By definition deeply immutable
var foo2: Foo = Foo() // By definition not immutable
// Backing property
private val _elementList = mutableListOf<Element>()
val elementList: List<Element>
get() = _elementList
companion object {
val foo1 = Foo() // In case developer want to communicate that Foo is mutable
val FOO1 = Foo() // In case developer want to communicate that Foo is deeply immutable
}
}
var `package` = "foo" // Any keyword is allowed when wrapped between backticks
const val fooBar = "FOO-BAR" // By definition deeply immutable
var FOO2: Foo = Foo() // By definition not immutable
class Bar {
val FOO_BAR = "FOO-BAR" // Class properties always start with lowercase, const is not allowed
// Incomplete backing property as public property 'elementList1' is missing
private val _elementList1 = mutableListOf<Element>()
// Invalid backing property as '_elementList2' is not a private property
val _elementList2 = mutableListOf<Element>()
val elementList2: List<Element>
get() = _elementList2
}
This rule can also be suppressed with the IntelliJ IDEA inspection suppression PropertyName
or ConstPropertyName
.
Rule id: property-naming
(standard
rule set)
No blank lines in list¶
Disallow blank lines to be used in lists before the first element, between elements, and after the last element.
Super type
Type argument list
Type constraint list
class BiAdapter<C : RecyclerView.ViewHolder, V1 : C, V2 : C, out A1, out A2>(
val adapter1: A1,
val adapter2: A2,
) : RecyclerView.Adapter<C>()
where A1 : RecyclerView.Adapter<V1>, A1 : ComposableAdapter.ViewTypeProvider,
A2 : RecyclerView.Adapter<V2>, A2 : ComposableAdapter.ViewTypeProvider {
// body
}
class BiAdapter<C : RecyclerView.ViewHolder, V1 : C, V2 : C, out A1, out A2>(
val adapter1: A1,
val adapter2: A2
) : RecyclerView.Adapter<C>()
where
A1 : RecyclerView.Adapter<V1>, A1 : ComposableAdapter.ViewTypeProvider,
A2 : RecyclerView.Adapter<V2>, A2 : ComposableAdapter.ViewTypeProvider
{
// body
}
Type parameter list
Value argument list
Value parameter list
Rule id: no-blank-line-in-list
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
No consecutive comments¶
Consecutive comments are disallowed in following cases: - Any mix of a consecutive kdoc, a block comment or an EOL comment unless separated by a blank line in between - Consecutive KDocs (even when separated by a blank line) - Consecutive block comments (even when separated by a blank line)
Consecutive EOL comments are always allowed as they are often used instead of a block comment.
// An EOL comment
// may be followed by another EOL comment
val foo = "foo"
// Different comment types (including KDoc) may be consecutive ..
/*
* ... but do need to be separated by a blank line ...
*/
/**
* ... but a KDoc can not be followed by an EOL or a block comment or another KDoc
*/
fun bar() = "bar"
Rule id: no-consecutive-comments
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
No empty file¶
A kotlin (script) file should not be empty. It needs to contain at least one declaration. Files only contain a package and/or import statements are as of that disallowed.
Rule id: no-empty-file
No empty first line at start in class body¶
Detect blank lines at start of a class body.
Rule id: no-empty-first-line-in-class-body
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
No single line block comment¶
A single line block comment should be replaced with an EOL comment when possible.
Rule id: no-single-line-block-comment
(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 maximum length of a line. This rule does not apply in a number of situations. 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`() {
}
Configuration setting | ktlint_official | intellij_idea | android_studio |
---|---|---|---|
ktlint_ignore_back_ticked_identifier Defines whether the backticked identifier (``) should be ignored. |
false |
false |
false |
max_line_length Maximum length of a (regular) line. |
140 | off |
100 |
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¶
Avoid using unnecessary semicolons.
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.
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 whitelisted imports.
Configuration setting | ktlint_official | intellij_idea | android_studio |
---|---|---|---|
ij_kotlin_packages_to_use_import_on_demand Defines allowed wildcard imports. |
- | java.util.*, kotlinx.android.synthetic.** |
java.util.*, kotlinx.android.synthetic.** |
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
:
Configuration setting ij_kotlin_packages_to_use_import_on_demand
is a comma separated string of import paths. This can be a full path, e.g. "java.util.List.", or a wildcard path, e.g. "kotlin.". Use "*" as wildcard for package and all subpackages.
The layout can be composed by the following symbols:
*
- wildcard. There must be at least one entry of a single wildcard to match all other imports. Matches anything after a specified symbol/import as well.|
- blank line. Supports only single blank lines between imports. No blank line is allowed in the beginning or end of the layout.^
- alias import, e.g. "^android.*" will match all android alias imports, "^" will match all other alias imports.
Examples:
ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list
ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout
Rule id: no-wildcard-imports
(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.
// In case `ktlint_function_signature_body_expression_wrapping` is set to `default` or `multiline`
fun foo1() = "some-result"
// In case `ktlint_function_signature_body_expression_wrapping` is set to `always`
fun foo2() =
"some-result"
fun foo3() {
// do something
}
// In case `ktlint_function_signature_body_expression_wrapping` is set to `default` or `multiline`
fun bar1(): String = "some-result"
// In case `ktlint_function_signature_body_expression_wrapping` is set to `always`
fun bar2(): String =
"some-result"
fun bar3(): String {
doSomething()
return "some-result"
}
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)
Parameter list spacing¶
Consistent spacing inside the parameter list.
Rule id: parameter-list-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)
Try catch finally spacing¶
Enforce consistent spacing in try { .. } catch { .. } finally { .. }
.
Rule id: try-catch-finally-spacing
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
Type argument list spacing¶
Spacing before and after the angle brackets of a type argument list.
Rule id: type-argument-list-spacing
(standard
rule set)
Type parameter list spacing¶
Spacing after a type parameter list in function and class declarations.
Rule id: type-parameter-list-spacing
(standard
rule set)
Unary operator spacing¶
No spaces around unary operators.
Rule id: unary-op-spacing
(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)
String template indent¶
Enforce consistent string template indentation for multiline string templates which are post-fixed with .trimIndent()
. The opening and closing """
are placed on separate lines and the indentation of the content of the template is aligned with the """
.
Rule id: string-template-indent
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
Trailing comma on call site¶
Consistent removal (default) or adding of trailing commas on call site.
Configuration setting | ktlint_official | intellij_idea | android_studio |
---|---|---|---|
ij_kotlin_allow_trailing_comma_on_call_site Defines whether a trailing comma (or no trailing comma) should be enforced on the calling site, e.g. argument-list, when-entries, lambda-arguments, indices, etc. When set, IntelliJ IDEA uses this property to allow usage of a trailing comma by discretion of the developer. KtLint however uses this setting to enforce consistent usage of the trailing comma when set. |
true |
true |
false |
Note
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.
KtLint values consistent formatting more than a per-situation decision, and therefore uses this setting to enforce/disallow usage of trailing comma's on the calling site.
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.
Configuration setting | ktlint_official | intellij_idea | android_studio |
---|---|---|---|
ij_kotlin_allow_trailing_comma Defines whether a trailing comma (or no trailing comma) should be enforced on the defining site, e.g. parameter-list, type-argument-list, lambda-value-parameters, enum-entries, etc. When set, IntelliJ IDEA uses this property to allow usage of a trailing comma by discretion of the developer. KtLint however uses this setting to enforce consistent usage of the trailing comma when set. |
true |
true |
false |
Note
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.
KtLint values consistent formatting more than a per-situation decision, and therefore uses this setting to enforce/disallow usage of trailing comma's in declarations.
Rule id: trailing-comma-on-declaration-site
(standard
rule set)
Type argument comment¶
Disallows comments to be placed at certain locations inside a type argument (list). A KDoc is not allowed.
Note
In some projects it is an accepted practice to use EOL comments to document the parameter before the comma as is shown below:
Although this code sample might look ok, it is semantically and programmatically unclear to which typesome comment
refers. From the developer perspective it might be clear that it belongs to type Bar1
. From the parsers perspective, it does belong to type Bar2
.
Rule id: type-argument-comment
(standard
rule set)
Type parameter comment¶
Disallows comments to be placed at certain locations inside a type parameter (list). A KDoc is not allowed.
Note
In some projects it is an accepted practice to use EOL comments to document the parameter before the comma as is shown below:
Although this code sample might look ok, it is semantically and programmatically unclear on which parameter some comment
refers. From the developer perspective it might be clear that it belongs to type Bar1
. From the parsers perspective, it does belong to type Bar2
.
Rule id: type-parameter-comment
(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)
Value argument comment¶
Disallows comments to be placed at certain locations inside a value argument (list). A KDoc is not allowed.
Note
In Ktlint 1.1.x EOL comments like below are disallowed. This will be reverted in Ktlint 1.2.
Rule id: value-argument-comment
(standard
rule set)
Value parameter comment¶
Disallows comments to be placed at certain locations inside a value argument (list). A KDoc is allowed but must start on a separate line.
Note
In Ktlint 1.1.x EOL comments like below are disallowed. This will be reverted in Ktlint 1.2.
Rule id: value-parameter-comment
(standard
rule set)
Wrapping¶
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)
Chain wrapping¶
When wrapping chained calls .
, ?.
and ?:
should be placed on the next line
Rule id: chain-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)
Content receiver wrapping¶
Wraps the content receiver list to a separate line regardless of maximum line length. If the maximum line length is configured and is exceeded, wrap the context receivers and if needed its projection types to separate lines.
// Always wrap regardless of whether max line length is set
context(Foo)
fun fooBar()
// Wrap each context receiver to a separate line when the
// entire context receiver list does not fit on a single line
context(
Fooooooooooooooooooo1,
Foooooooooooooooooooooooooooooo2
)
fun fooBar()
// Wrap each context receiver to a separate line when the
// entire context receiver list does not fit on a single line.
// Also, wrap each of it projection types in case a context
// receiver does not fit on a single line after it has been
// wrapped.
context(
Foooooooooooooooo<
Foo,
Bar,
>
)
fun fooBar()
// Should be wrapped regardless of whether max line length is set
context(Foo) fun fooBar()
// Should be wrapped when the entire context receiver list does not
// fit on a single line
context(Fooooooooooooooooooo1, Foooooooooooooooooooooooooooooo2)
fun fooBar()
// Should be wrapped when the entire context receiver list does not
// fit on a single line. Also, it should wrap each of it projection
// type in case a context receiver does not fit on a single line
// after it has been wrapped.
context(Foooooooooooooooo<Foo, Bar>)
fun fooBar()
Rule id: context-receiver-wrapping
(standard
rule set)
Enum wrapping¶
An enum should be a single line, or each enum entry has to be placed on a separate line. In case the enumeration contains enum entries and declarations those are to be separated by a blank line.
Rule id: enum-wrapping
(standard
rule set)
If else wrapping¶
A single line if-statement should be kept simple. It may contain no more than one else-branch. The branches may not be wrapped in a block.
Rule id: if-else-wrapping
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
Multiline expression wrapping¶
Multiline expression on the right hand side of an expression are forced to start on a separate line. Expressions in return statement are excluded as that would result in a compilation error.
Rule id: multiline-expression-wrapping
(standard
rule set)
Note
This rule is only run when ktlint_code_style
is set to ktlint_official
or when the rule is enabled explicitly.
Parameter list wrapping¶
When class/function signature doesn't fit on a single line, each parameter must be on a separate line.
Note
Wrapping of parameters is also influenced by the function-signature
rule.
// If `ktlint_class_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than` equals
// `unset` the parameters are not wrapped as long as they fit on a single line
class ClassA(paramA: String, paramB: String, paramC: String)
class ClassA(
paramA: String,
paramB: String,
paramC: String
)
// If `ktlint_function_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than` equals
// `unset` the parameters are not wrapped as long as they fit on a single line
fun f(a: Any, b: Any, c: Any)
fun f(
a: Any,
b: Any,
c: Any
)
fun foo(
@Bar fooBar: FooBar
)
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)
Statement wrapping¶
A function, class/object body or other block body statement has to be placed on different line than the braces of the body block.
Rule id: statement-wrapping
Wrapping¶
Inserts missing newlines (for example between parentheses of a multi-line function call).
Rule id: wrapping
(standard
rule set)