doc: formalize `auto` usage in C++ style guide

We generally avoid using `auto` if not necessary. This
formalizes this rules by writing them down in the C++ style guide.

PR-URL: https://github.com/nodejs/node/pull/23028
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

1 files changed, 19 insertions, 0 deletions

diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md
index 14776779fd..ae0135b5c0 100644
--- a/CPP_STYLE_GUIDE.md
+++ b/CPP_STYLE_GUIDE.md
@@ -20,6 +20,7 @@
   * [Ownership and Smart Pointers](#ownership-and-smart-pointers)
 * [Others](#others)
   * [Type casting](#type-casting)
+  * [Using `auto`](#using-auto)
   * [Do not include `*.h` if `*-inl.h` has already been included](#do-not-include-h-if--inlh-has-already-been-included)
   * [Avoid throwing JavaScript errors in C++ methods](#avoid-throwing-javascript-errors-in-c)
     * [Avoid throwing JavaScript errors in nested C++ methods](#avoid-throwing-javascript-errors-in-nested-c-methods)
@@ -209,6 +210,24 @@ Never use `std::auto_ptr`. Instead, use `std::unique_ptr`.
 - Use `static_cast` for casting whenever it works
 - `reinterpret_cast` is okay if `static_cast` is not appropriate
 
+### Using `auto`
+
+Being explicit about types is usually preferred over using `auto`.
+
+Use `auto` to avoid type names that are noisy, obvious, or unimportant. When
+doing so, keep in mind that explicit types often help with readability and
+verifying the correctness of code.
+
+```cpp
+for (const auto& item : some_map) {
+  const KeyType& key = item.first;
+  const ValType& value = item.second;
+  // The rest of the loop can now just refer to key and value,
+  // a reader can see the types in question, and we've avoided
+  // the too-common case of extra copies in this iteration.
+}
+```
+
 ### Do not include `*.h` if `*-inl.h` has already been included
 
 Do