Why the *Async naming convention for functions returning Deferreds?

Question

Intellij has an inspection (i.e. lint check) that tells you functions that return Deferred should be named something ending in Async.

Naming conventions like these make sense to me in dynamically typed languages. But Kotlin has such a nice type-checker and ecosystem of tooling, so why rely on the convention?

Especially because Kotlin coroutines bake structured concurrency in, the function will probably also take a CoroutineScope parameter, which would serve the same visual cue at the call site:

suspend fun doStuff() = coroutineScope {
  doStuffAsync(this /* CoroutineScope */).await()
  //...
}

As a side note, I understand the inspection's message that you'd rarely want a function that returns a Deferred instead of a suspend function. That's not my question. My question assumes that you know what you're doing and you want a Deferred.

Answer 1

To begin with, a function should almost never return a Deferred that comes from an async block. It is up to the caller to wrap some unit of work into an async while doing other work in the foreground, then await on the async result before returning, and wrap all that code in a coroutineScope.

The intended source of Deferred instances is the adaptation layer between Kotlin coroutines and 3rd-party async APIs. For such calls it does make sense to put Async in the name and even some Java APIs follow this convention. For example, you may have a

fun fetchOrder(id: String): Deferred<Order>

and use it as

val orderCancelled = fetchOrder(orderId).isCancelled

This code is type-safe and type-correct, it doesn't cause any compiler errors. It looks like it's fetching an order from a remote system and then checking the order status (whether it's cancelled), but what it's actually doing is getting a Deferred<Order> and checking whether the Deferred is cancelled. Because your function name is missing Async, this kind of error is hard to spot.

Yes, you can also request the IDE to give you the return type, but it may take a while before you even suspect what's going on.