proposal: `discarded_futures`

[pq]

discarded_futures

Description

Don't discard futures in async functions.

Details

Making asynchronous calls in non-async functions is usually the sign of a programming error. In general these functions should be marked async and such futures should likely be awaited (as enforced by unawaited_futures).

In case you really do want to discard a Future in a non-async function, the recommended way is to use unawaited from dart:async. The // ignore and // ignore_for_file comments also work.

Kind

Error

Good Examples

Future<void> recreateDir(String path) async {
  await deleteDir(path);
  await createDir(path);
}

Future<void> deleteDir(String path) async {}

Future<void> createDir(String path) async {}

Bad Examples

void recreateDir(String path) {
  deleteDir(path);
  createDir(path);
}

Future<void> deleteDir(String path) async {}

Future<void> createDir(String path) async {}

Discussion

See #57653, #58512 and unawaited_futures.

/fyi @eernstg @diegovar @dowski @bsutton

Discussion checklist

• List any existing rules this proposal modifies, complements, overlaps or conflicts with.
• List any relevant issues (reported here, the SDK Tracker, or elsewhere).
• If there's any prior art (e.g., in other linters), please add references here.
• If this proposal corresponds to Effective Dart or Flutter Style Guide advice, please call it out. (If there isn’t any corresponding advice, should there be?)
• If this proposal is motivated by real-world examples, please provide as many details as you can. Demonstrating potential impact is especially valuable.

[eernstg]

Looks good! I always thought that it is a footgun to allow futures to be discarded silently just because someone forgot to put async on the enclosing function. ;)

[bwilkerson]

I assume that unawaited would still work to mark exceptions to the rule, even in a sync environment.

[pq]

Thanks for taking a look @eernstg! If you have any thoughts for how we can best communicate the nuances in our docs, I'd really welcome any contributions. 😄

I assume that unawaited would still work to mark exceptions to the rule, even in a sync environment.

Ah! This is a great point and I admit I'd overlooked it. It does sound reasonable to me. Thanks!

(EDIT: description updated.)

[bwilkerson]

I'm also happy to help with the docs, though it seems like it ought to be fairly easy to describe using the modifiers that go on the function body.

Note that I've started looking at re-writing some of the lint docs in preparation for integrating the two diagnostic documentation locations.

[pq]

I'm also happy to help with the docs

Fantastic. Thank you!

Note that I've started looking at re-writing some of the lint docs in preparation for integrating the two diagnostic documentation locations.

Super! 🚀

[eernstg]

Is there a lint family just below the surface here, with the common topic "you forgot to make this function async"?

[pq]

Maybe? I've been thinking about this too. I do wonder though if in practice if we can tell the difference between places where someone intends for a function to be async (and just forget to mark it so) and places where they didn't realize they were calling something async (and may not want to...)