Проверка неиспользуемых возвращаемых значений

Настройка проверки неиспользуемых возвращаемых значений

Вы можете управлять тем, как компилятор сообщает об игнорируемых результатах, с помощью параметра компилятора -Xreturn-value-checker.

Он поддерживает следующие режимы:

• disable отключает проверку неиспользуемых возвращаемых значений (по умолчанию).

• check включает проверку и сообщает о предупреждениях для игнорируемых результатов помеченных функций.

• full включает проверку, считает все функции в проекте помеченными и сообщает о предупреждениях для игнорируемых результатов.

Чтобы использовать проверку неиспользуемых возвращаемых значений в проекте, добавьте параметр компилятора в файл конфигурации сборки:

// build.gradle(.kts)
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xreturn-value-checker=check")
    }
}

<!-- pom.xml -->
<plugin>
    <groupId>org.jetbrains.kotlin</groupId>
    ..
    <configuration>
        <args>
            <arg>-Xreturn-value-checker=check</arg>
        </args>
    </configuration>
</plugin>

Пометка функций для проверки игнорируемых результатов

Если задать параметр компилятора -Xreturn-value-checker равным check, проверка будет сообщать об игнорируемых результатах только для помеченных выражений, как это сделано для большинства функций стандартной библиотеки Kotlin.

Чтобы пометить собственный код, используйте аннотацию @MustUseReturnValues. Её можно применить к файлу, классу или функции в зависимости от области, которую должна охватывать проверка.

Например, можно пометить весь файл:

// Marks all functions and classes in this file so the checker reports unused return values
@file:MustUseReturnValues

package my.project

fun someFunction(): String

Или отдельный класс:

// Marks all functions in this class so the checker reports unused return values
@MustUseReturnValues
class Greeter {
    fun greet(name: String): String = "Hello, $name"
}

fun someFunction(): Int = ...

Отключение сообщений об игнорируемых результатах

Чтобы отключить сообщения для определённых функций, аннотируйте их с помощью @IgnorableReturnValue. Аннотируйте функции, для которых игнорирование результата является обычным и ожидаемым поведением, например MutableList.add:

@IgnorableReturnValue
fun <T> MutableList<T>.addAndIgnoreResult(element: T): Boolean {
    return add(element)
}

Можно отключить предупреждение, не аннотируя саму функцию. Для этого присвойте результат специальной безымянной переменной, используя синтаксис с подчёркиванием (_):

// Non-ignorable function
fun computeValue(): Int = 42

fun main() {

    // Reports a warning: result is ignored
    computeValue()

    // Suppresses the warning only at this call site with a special unused variable
    val _ = computeValue()
}

@MustUseReturnValues
interface Greeter {
    fun greet(name: String): String
}

object SilentGreeter : Greeter {
    @IgnorableReturnValue
    override fun greet(name: String): String = ""
}

fun check(g: Greeter) {
    // Reports a warning: unused return value
    g.greet("John")

    // No warning
    SilentGreeter.greet("John")
}

Проверка неиспользуемых результатов в функциях высшего порядка

Некоторые функции высшего порядка, например функция области видимости let, возвращают результат лямбда-выражения. Чтобы проверять неиспользуемые результаты лямбда-выражений в функциях высшего порядка, добавьте контракт returnsResultOf(), имеющий статус экспериментального, в контракт функции.

Вот пример:

import kotlin.contracts.ExperimentalContracts
import kotlin.contracts.contract

@OptIn(ExperimentalContracts::class)
inline fun <T, R> T.customLet(block: (T) -> R): R {
    contract {
        returnsResultOf(block)
    }
    return block(this)
}

Затем можно использовать функцию с таким контрактом, например .customLet(), чтобы проверить, используется ли результат лямбда-выражения:

fun handleNullablePackageName(packageName: String?, builder: StringBuilder) {
    // The checker doesn't report a warning because the return value of append() can be ignored
    packageName?.customLet { builder.append(it) }

    // The checker reports a warning because the returned string is unused
    packageName?.customLet { "kotlin.$it" }
}

Чтобы включить его использование в проекте, добавьте следующий параметр компилятора в файл сборки:

// build.gradle(.kts)
kotlin {
    compilerOptions {
        freeCompilerArgs.add("-Xallow-returns-result-of")
    }
}

<!-- pom.xml -->
<build>
    <plugins>
        <plugin>
            <groupId>org.jetbrains.kotlin</groupId>
            <artifactId>kotlin-maven-plugin</artifactId>
            <configuration>
                <args>
                    <arg>-Xallow-returns-result-of</arg>
                </args>
            </configuration>
        </plugin>
    </plugins>
</build>

Совместимость с аннотациями Java

Некоторые библиотеки Java используют похожие механизмы с другими аннотациями. Проверка неиспользуемых возвращаемых значений считает следующие аннотации эквивалентными использованию @MustUseReturnValues:

• com.google.errorprone.annotations.CheckReturnValue

• edu.umd.cs.findbugs.annotations.CheckReturnValue

• org.jetbrains.annotations.CheckReturnValue

• org.springframework.lang.CheckReturnValue

• org.jooq.CheckReturnValue

Она также считает аннотацию com.google.errorprone.annotations.CanIgnoreReturnValue эквивалентной использованию @IgnorableReturnValue.