Merge pull request #2798 from corob-msft/dmitrykobets-c26820

Document new rule C26820

Author: GitHubber17

docs/code-quality/c26820.md

@@ -0,0 +1,43 @@
+---
+title: C26820
+description: "Reference for Microsoft C++ Code Analysis warning C26820 in Visual Studio."
+ms.date: 04/07/2020
+f1_keywords: ["C26820"]
+helpviewer_keywords: ["C26820"]
+---
+# C26820
+
+> Assigning by value when a const-reference would suffice, use const T& instead (p.9).
+
+For more information, see [P.9: Don't waste time or space](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#p9-dont-waste-time-or-space) in the C++ Core Guidelines.
+
+This check covers non-obvious and easy-to-miss behavior when assigning a reference to a variable marked `auto`. The type of the `auto` variable is resolved to a value rather than a reference, and an implicit copy is made.
+
+## Remarks
+
+- This warning isn't raised for scalars, smart pointers, or views. It's also not raised for types whose size isn't more than twice the platform-dependent pointer size.
+- This warning isn't raised when the variable gets mutated, as marking it `auto&` would introduce side-effects to the mutation.
+- This warning isn't raised when the reference comes from a temporary object, because that results in a dangling reference. For example:
+
+  ```cpp
+  std::optional<int> TryGetNumber();
+  ...
+  const auto& val = TryGetNumber().value();
+  val++; // Temporary from TryGetNumber() is destroyed and val is now dangling
+  ```
+
+## Example
+
+This sample shows a variable definition that makes a potentially expensive copy when assigned a reference:
+
+```cpp
+MyClass& ref = ...;
+auto var = ref; // C26820 (`var` takes a copy of the object referred to by `ref`)
+```
+
+To resolve this issue, declare the variable by using `const auto&` instead:
+
+```cpp
+MyClass& ref = ...;
+const auto& var = ref; // OK
+```

docs/code-quality/toc.yml

@@ -570,6 +570,8 @@
       href: c26810.md
     - name: C26811
       href: c26811.md
+    - name: C26820
+      href: c26820.md
     - name: C28020
       href: c28020.md
     - name: C28021