Skip to main content

Inconsistent parameter order in overloads

DiagnosticINCONSISTENT_PARAMETER_ORDER_IN_OVERLOADS
Default severityError
Gradle propertyinconsistentParameterOrderInOverloads
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 internal overloads 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​

build.gradle.kts
apiWatchdog {
inconsistentParameterOrderInOverloads = WatchdogSeverity.ERROR
}

For a direct compiler call:

-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=INCONSISTENT_PARAMETER_ORDER_IN_OVERLOADS:error

See also​