From 4092ac81d26a10f80d97e295ad4ed8096ffcb5ed Mon Sep 17 00:00:00 2001
From: Parker Lougheed <parlough@gmail.com>
Date: Wed, 26 Feb 2025 21:58:36 -0600
Subject: [PATCH] Update unused callback parameter style entry for wildcards
 (#6456)

Resolves https://github.com/dart-lang/site-www/issues/6446
---
 .../misc/lib/effective_dart/style_good.dart   | 11 ++++-
 src/content/effective-dart/_toc.md            |  2 +-
 src/content/effective-dart/style.md           | 42 +++++++++++++------
 3 files changed, 39 insertions(+), 16 deletions(-)

diff --git a/examples/misc/lib/effective_dart/style_good.dart b/examples/misc/lib/effective_dart/style_good.dart
index 426d7ad2e7..6400dc4a72 100644
--- a/examples/misc/lib/effective_dart/style_good.dart
+++ b/examples/misc/lib/effective_dart/style_good.dart
@@ -117,11 +117,18 @@ class Dice {
 
 void unusedCallbackParams() {
   var futureOfVoid = Future<void>.value();
-  // #docregion unused-callback-params
+  // #docregion unused-callback-param
   futureOfVoid.then((_) {
     print('Operation complete.');
   });
-  // #enddocregion unused-callback-params
+  // #enddocregion unused-callback-param
+
+  futureOfVoid
+  // #docregion unused-callback-params-multiple
+  .onError((_, _) {
+    print('Operation failed.');
+  });
+  // #enddocregion unused-callback-params-multiple
 }
 
 //----------------------------------------------------------------------------
diff --git a/src/content/effective-dart/_toc.md b/src/content/effective-dart/_toc.md
index 4811be1ba2..b2c7d24ddb 100644
--- a/src/content/effective-dart/_toc.md
+++ b/src/content/effective-dart/_toc.md
@@ -22,7 +22,7 @@ the project:
 * <a href='/effective-dart/style#do-name-other-identifiers-using-lowercamelcase'>DO name other identifiers using <code>lowerCamelCase</code>.</a>
 * <a href='/effective-dart/style#prefer-using-lowercamelcase-for-constant-names'>PREFER using <code>lowerCamelCase</code> for constant names.</a>
 * <a href='/effective-dart/style#do-capitalize-acronyms-and-abbreviations-longer-than-two-letters-like-words'>DO capitalize acronyms and abbreviations longer than two letters like words.</a>
-* <a href='/effective-dart/style#prefer-using-_-__-etc-for-unused-callback-parameters'>PREFER using <code>_</code>, <code>__</code>, etc. for unused callback parameters.</a>
+* <a href='/effective-dart/style#prefer-using-wildcards-for-unused-callback-parameters'>PREFER using wildcards for unused callback parameters.</a>
 * <a href='/effective-dart/style#dont-use-a-leading-underscore-for-identifiers-that-arent-private'>DON'T use a leading underscore for identifiers that aren't private.</a>
 * <a href='/effective-dart/style#dont-use-prefix-letters'>DON'T use prefix letters.</a>
 * <a href='/effective-dart/style#dont-explicitly-name-libraries'>DON'T explicitly name libraries.</a>
diff --git a/src/content/effective-dart/style.md b/src/content/effective-dart/style.md
index 08840fffe5..f59f1fab0f 100644
--- a/src/content/effective-dart/style.md
+++ b/src/content/effective-dart/style.md
@@ -279,21 +279,32 @@ var tvSet = Television();
 var mrRogers = 'hello, neighbor';
 ```
 
-### PREFER using `_`, `__`, etc. for unused callback parameters
+<a id="prefer-using-_-__-etc-for-unused-callback-parameters" aria-hidden="true"></a>
+
+### PREFER using wildcards for unused callback parameters
 
 Sometimes the type signature of a callback function requires a parameter,
 but the callback implementation doesn't _use_ the parameter.
-In this case, it's idiomatic to name the unused parameter `_`.
-If the function has multiple unused parameters, use additional
-underscores to avoid name collisions: `__`, `___`, etc.
+In this case, it's idiomatic to name the unused parameter `_`,
+which declares a [wildcard variable][wildcards] that is non-binding.
 
-<?code-excerpt "style_good.dart (unused-callback-params)"?>
+<?code-excerpt "style_good.dart (unused-callback-param)"?>
 ```dart tag=good
 futureOfVoid.then((_) {
   print('Operation complete.');
 });
 ```
 
+Because wildcard variables are non-binding,
+you can name multiple unused parameters `_`.
+
+<?code-excerpt "style_good.dart (unused-callback-params-multiple)"?>
+```dart tag=good
+.onError((_, _) {
+  print('Operation failed.');
+});
+```
+
 This guideline is only for functions that are both *anonymous and local*.
 These functions are usually used immediately in a context where it's
 clear what the unused parameter represents.
@@ -302,17 +313,22 @@ so their parameters must be named so that it's clear what each parameter is for,
 even if it isn't used.
 
 :::version-note
-Since Dart 3.7, the [wildcard variable `_`][] no longer creates a variable, so you can
-use `_` for multiple parameters simultaneously without name collision:
+Declaring non-binding [wildcard variables][wildcards] requires
+a [language version][] of at least 3.7.
 
-```dart tag=good
-(_, _) {
-  print('error');
-}
-```
+In earlier language versions, use additional underscores to
+work around name collisions, such as `__` and `___`.
+To enforce not using them and simplify the migration to wildcards later on,
+enable the [`no_wildcard_variable_uses`][] lint.
+
+To help migrate from this convention to wildcard variables,
+enable the [`unnecessary_underscores`][] lint.
 :::
 
-[wildcard variable `_`]: /language/variables#wildcard-variables
+[wildcards]: /language/variables#wildcard-variables
+[language version]: /resources/language/evolution#language-versioning
+[`no_wildcard_variable_uses`]: /tools/linter-rules/no_wildcard_variable_uses
+[`unnecessary_underscores`]: /tools/linter-rules/unnecessary_underscores
 
 ### DON'T use a leading underscore for identifiers that aren't private