Merge pull request MicrosoftDocs#2651 from Xazax-hun/patch-2

Colin Robertson · web-flow · commit fe10f142b7c2 · 2020-12-14T13:16:44.000-08:00
Clarify behavior of C26409 for delete this idiom
diff --git a/docs/code-quality/c26409.md b/docs/code-quality/c26409.md
@@ -1,7 +1,7 @@
 ---
-description: "Learn more about: C26409 NO_NEW_DELETE"
+description: "Learn more about CppCoreCheck rule C26409: avoid explicit new and delete."
 title: C26409
-ms.date: 08/20/2020
+ms.date: 12/14/2020
 ms.topic: "conceptual"
 f1_keywords: ["C26409"]
 helpviewer_keywords: ["C26409"]
@@ -11,7 +11,7 @@ ms.assetid: a3b3a229-d566-4be3-bd28-2876ccc8dc37
 
 > `Avoid calling new and delete explicitly, use std::make_unique<T> instead (r.11).`
 
-Even if code is clean of calls to`malloc()` and `free()`, we still suggest that you consider better options than explicit use of operators [`new` and `delete`](../cpp/new-and-delete-operators.md).
+Even if code is clean of calls to `malloc` and `free`, we still suggest that you consider better options than explicit use of operators [`new` and `delete`](../cpp/new-and-delete-operators.md).
 
 **C++ Core Guidelines**:\
 [R.11: Avoid calling new and delete explicitly](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r11-avoid-calling-new-and-delete-explicitly)
@@ -22,7 +22,7 @@ The ultimate fix is to use smart pointers and appropriate factory functions, suc
 
 - The checker warns on calls to any kind of operator **`new`** or **`delete`**: scalar, vector, overloaded versions (global and class-specific), and placement versions. The placement **`new`** case may require some clarifications in the Core Guidelines for suggested fixes, and may be omitted in the future.
 
-## Example
+## Examples
 
 This example shows C26409 is raised for explicit **`new`** and **`delete`**. Consider using smart pointer factory functions such as `std::make_unique` instead.
 
@@ -35,3 +35,24 @@ void f(int i)
     auto unique = std::make_unique<int[]>(i); // prefer using smart pointers over new and delete
 }
 ```
+
+There's a C++ idiom, `delete this`, that triggers this warning. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example:
+
+```cpp
+class MyReferenceCountingObject final
+{
+public:
+    void AddRef();
+    void Release() noexcept
+    {
+        ref_count_--;
+        if (ref_count_ == 0)
+        {
+            [[gsl::suppress(i.11)]]
+            delete this; 
+        }
+    }
+private:
+    unsigned int ref_count_{1};
+};
+```
