Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Add documents about trailing comma is disabled when wrapping is enabled #1800

Merged
merged 5 commits into from
Feb 1, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 50 additions & 4 deletions docs/rules/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,30 +178,76 @@ Consistent removal (default) or adding of trailing comma's on call site.
!!! 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](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) leaves it to the developer's discretion to use trailing comma's on the call site, it also states that usage of trailing commas has several benefits:
Although the [Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) leaves it to the developer's discretion to use trailing comma's 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](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded. Because it cannot provide proper formatting with unwrapped calls. (see [dependencies](./dependencies.md)).

=== "[:material-heart:](#) Ktlint"

```kotlin
FooWrapper(
Foo(
a = 3,
b = 4,
),
)
```
=== "[:material-heart-off-outline:](#) Disallowed"

```kotlin
FooWrapper(Foo(
a = 3,
b = 4,
),) // it's weird to insert "," between unwrapped (continued) parenthesis
```


Rule id: `trailing-comma-on-call-site`

## Trailing comma on declaration site

Consistent removal (default) or adding of trailing comma's 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.
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.
paul-dingemans marked this conversation as resolved.
Show resolved Hide resolved

!!! 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.
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.
sanggggg marked this conversation as resolved.
Show resolved Hide resolved

The Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) encourages the usage of trailing comma's on the declaration site, but leaves it to the developer's discretion to use trailing comma's on the call site. But next to this, it also states that usage of trailing commas has several benefits:
The [Kotlin coding conventions](https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods) encourages the usage of trailing comma's on the declaration site, but leaves it to the developer's discretion to use trailing comma's 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](#wrapping) rule (or, before version `0.45.0`, the [Indentation](#indentation) rule) is disabled or not loaded. Because it cannot provide proper formatting with unwrapped declarations. (see [dependencies](./dependencies.md)).

=== "[:material-heart:](#) Ktlint"

```kotlin
class FooWrapper(
val foo = Foo(
a = 3,
b = 4,
),
)
```
=== "[:material-heart-off-outline:](#) Disallowed"

```kotlin
class FooWrapper(val foo = Foo(
a = 3,
b = 4,
),) // it's weird to insert "," between unwrapped (continued) parenthesis
```


Rule id: `trailing-comma-on-declaration-site`

## Wrapping
Expand Down