Skip to main content

Boolean parameters in public API

BOOLEAN_PARAMETER_PUBLIC_API reports Boolean value parameters of public functions.

DiagnosticBOOLEAN_PARAMETER_PUBLIC_API
Default severityError
Gradle propertybooleanParameterPublicApi
Exemption@IntentionallyBooleanParameter

What it reports​

Every value parameter, and every context parameter, of a public or protected function whose type is Boolean, including the declared element type of vararg parameter.

@file:JvmName("Work")



/** Processes pending data, optionally favoring speed over memory use. */

public fun doWork(optimizeForSpeed: Boolean) {}

Rationale​

At the call site, a positional true/false argument reads as noise: resize(true) says nothing about what turns on. Users can't be forced to use named arguments yet, so the meaning depends on whoever reads the call site remembering the parameter name. See the Kotlin API guidelines on avoiding Boolean arguments.

Don't​

@file:JvmName("Logging")



/** Controls whether diagnostic messages are recorded. */

public fun setLogging(enabled: Boolean) {}

Do​

@file:JvmName("Logging")



/** Enables logging. */

public fun enableLogging() {}



/** Disables logging. */

public fun disableLogging() {}

Notes​

  • @PublishedApi internal functions are not reported because library users cannot call them in source.

  • A nullable Boolean? parameter is still a positional flag, just a three-state one, so it is reported the same way. It is also reported in Nullable Booleans in public API.

  • A type alias to Boolean doesn't change what users pass and is still reported.

  • A Boolean context parameter is reported too, and it hides the flag even better than a positional argument: the caller writes nothing at the call site, and the value is picked up from whatever Boolean happens to be in scope there.

    context(verbose: Boolean)

    public fun logLine(message: String) {}

    Legacy context receivers are not reported: K2 no longer resolves them, so they can't reach a published API.

  • Overrides are not reported: their signature is fixed by the overridden declaration, which is reported instead.

  • Constructors, and constructor functions - factory functions named after the type they create, such as fun Widget(visible: Boolean): Widget - are not reported.

  • Boolean return types and Boolean properties are not arguments and are not reported.

Exemption​

Apply @IntentionallyBooleanParameter when the parameter's meaning is unmistakable from the function name, such as setLogging(enabled: Boolean).

@file:JvmName("Logging")



/** Controls whether diagnostic messages are recorded. */

@IntentionallyBooleanParameter(reason = ExemptionReason.API_DESIGN)

public fun setLogging(enabled: Boolean) {}

Configuration​

apiWatchdog {

    booleanParameterPublicApi = WatchdogSeverity.WARNING

}

With direct compiler invocation:

-P plugin:org.jetbrains.kotlin.library.api.watchdog:diagnosticSeverity=BOOLEAN_PARAMETER_PUBLIC_API:warning

See also​