Inconsistent parameter order in overloads
| Diagnostic | INCONSISTENT_PARAMETER_ORDER_IN_OVERLOADS |
| Default severity | Error |
| Gradle property | inconsistentParameterOrderInOverloads |
| Exemption | @IntentionallyInconsistentParameterOrder |
What it reports
Public API overloads that share at least two parameter names but put them at different positions. The check reports swaps and extra parameters before or between shared parameters. Extra parameters at the end aren't reported.
Align shared parameter positions across the overload group.
public fun move(x: Int, y: Int) { }public fun move(x: Int, scale: Double, y: Int) { }
Rationale
Callers can reuse one overload's argument order in another and pass values to the wrong parameters. If the parameter types match, the mistake still compiles.
Don't
public fun draw(x: Int, y: Int) { }public fun draw(y: Int, x: Int, scale: Double) { }
Do
public fun draw(x: Int, y: Int) { }public fun draw(x: Int, y: Int, scale: Double) { }
Don't
public class Rect(width: Int, height: Int) {public constructor(height: Int, width: Int, scale: Double) : this(width, height)}
Do
public class Rect(width: Int, height: Int) {public constructor(width: Int, height: Int, scale: Double) : this(width, height)}
Don't
public class Grid {public fun fill(startIndex: Int, endIndex: Int) { }}public fun Grid.fill(endIndex: Int,startIndex: Int,color: Long,) { }
Do
public class Grid {public fun fill(startIndex: Int, endIndex: Int) { }}public fun Grid.fill(startIndex: Int,endIndex: Int,color: Long,) { }
Notes
The comparisons have these limits:
- Members of one class, including inherited members, share a group. Only the subtype's declaration reports an inherited mismatch.
- Top-level functions in one package share a group. Constructors of one class share a group.
- An extension also compares against its receiver's members. Only the extension reports that mismatch.
- Ordinary top-level functions don't compare against class members. Declarations from dependencies aren't checked.
- Overrides don't get diagnostics but are used in comparisons. An exemption on an override doesn't remove it from the comparisons.
@PublishedApi internaloverloads aren't used in comparisons.- A last parameter accepts a trailing lambda when its type is a function type, a
fun interface, or a Java SAM interface.
Exemption
If this is intended, apply @IntentionallyInconsistentParameterOrder to the function
or constructor.
Use the exemption when the declaration is part of the API design or must stay for backwards compatibility. The annotation removes that overload from all comparisons, unless the overload is an override.
public fun draw(x: Int, y: Int) { }@IntentionallyInconsistentParameterOrder(reason = ExemptionReason.FOR_BACKWARDS_COMPATIBILITY,)public fun draw(y: Int, x: Int, scale: Double) { }
Configuration
apiWatchdog {inconsistentParameterOrderInOverloads = WatchdogSeverity.ERROR}
For a direct compiler call:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=INCONSISTENT_PARAMETER_ORDER_IN_OVERLOADS:error