Merge pull request #2807 from MicrosoftDocs/master

4/13/2020 AM Publish

Author: Taojunshen

docs/code-quality/c26820.md

@@ -7,7 +7,7 @@ helpviewer_keywords: ["C26820"]
 ---
 # C26820
 
-> Assigning by value when a const-reference would suffice, use const T& instead (p.9).
+> Assigning by value when a const-reference would suffice, use const auto& 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.
 
@@ -31,13 +31,15 @@ This check covers non-obvious and easy-to-miss behavior when assigning a referen
 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`)
+const Object& MyClass::getRef() { ... }
+...
+auto ref = myclass.getRef(); // C26820 (`ref` takes a copy of the returned object)
 ```
 
 To resolve this issue, declare the variable by using `const auto&` instead:
 
 ```cpp
-MyClass& ref = ...;
-const auto& var = ref; // OK
+const Object& MyClass::getRef() { ... }
+...
+const auto& ref = myclass.getRef(); // OK
 ```

docs/code-quality/demo-sample.md

@@ -1,6 +1,7 @@
 ---
 title: Sample C++ project for code analysis
-ms.date: 11/04/2016
+description: "How to create a sample solution for use in the code analysis walkthrough for Microsoft C++ in Visual Studio."
+ms.date: 04/14/2020
 ms.topic: sample
 helpviewer_keywords:
   - "demo sample [Visual Studio ALM]"
@@ -9,47 +10,97 @@ ms.assetid: 09e1b9f7-5916-4ed6-a001-5c2d7e710682
 ---
 # Sample C++ project for code analysis
 
-This following procedures show you how to create the sample for [Walkthrough: Analyze C/C++ code for defects](../code-quality/walkthrough-analyzing-c-cpp-code-for-defects.md). The procedures create:
+The following procedures show you how to create the sample for [Walkthrough: Analyze C/C++ code for defects](../code-quality/walkthrough-analyzing-c-cpp-code-for-defects.md). The procedures create:
 
-- A Visual Studio solution named CppDemo.
+- A Visual Studio solution named *CppDemo*.
 
-- A static library project named CodeDefects.
+- A static library project named *CodeDefects*.
 
-- A static library project named Annotations.
+- A static library project named *Annotations*.
 
 The procedures also provide the code for the header and *.cpp* files for the static libraries.
 
 ## Create the CppDemo solution and the CodeDefects project
 
+::: moniker range=">=vs-2019"
+
 1. Open Visual Studio and select **Create a new project**
 
-1. Change language filter to **C++**
+1. In the **Create a new project** dialog, change the language filter to **C++**.
+
+1. Select **Windows Desktop Wizard** and choose the **Next** button.
+
+1. On the **Configure your new project** page, in the **Project name** text box, enter *CodeDefects*.
+
+1. In the **Solution name** text box, enter *CppDemo*.
+
+1. Choose **Create**.
+
+1. In the **Windows Desktop Project** dialog, change the **Application type** to **Static Library (.lib)**.
+
+1. Under **Additional options**, select **Empty project**.
+
+1. Choose **OK** to create the solution and project.
+
+::: moniker-end
+
+::: moniker range="vs-2017"
+
+1. Open Visual Studio. On the menu bar, choose **File** > **New** > **Project**.
+
+1. In the **New Project** dialog, select **Visual C++** > **Windows Desktop**.
+
+1. Select **Windows Desktop Wizard**.
+
+1. In the **Name** text box, enter *CodeDefects*.
+
+1. In the **Solution name** text box, enter *CppDemo*.
 
-1. Select **Empty Project** and click **Next**
+1. Choose **OK**.
 
-1. In the **Project Name** text box, type **CodeDefects**
+1. In the **Windows Desktop Project** dialog, change the **Application type** to **Static Library (.lib)**.
 
-1. In the **Solution name** text box, type **CppDemo**
+1. Under **Additional options**, select **Empty project**.
 
-1. Click **Create**
+1. Choose **OK** to create the solution and project.
 
-## Configure the CodeDefects project as a static library
+::: moniker-end
 
-1. In Solution Explorer, right-click **CodeDefects** and then click **Properties**.
+::: moniker range="vs-2015"
 
-1. Expand **Configuration Properties** and then click **General**.
+1. Open Visual Studio. On the menu bar, choose **File** > **New** > **Project**.
 
-1. In the **General** list, change **Configuration Type**, to **Static library (.lib)**.
+1. In the **New Project** dialog, select **Templates** > **Visual C++** > **Win32**.
 
-1. In the **Advanced** list, change **Target File Extension** to **.lib**
+1. Select **Win32 Console Application**.
+
+1. In the **Name** text box, enter *CodeDefects*.
+
+1. In the **Solution name** text box, enter *CppDemo*.
+
+1. Choose **OK**.
+
+1. In the **Win32 Application Wizard** dialog, choose the **Next** button.
+
+1. Change the **Application type** to **Static library**.
+
+1. Under **Additional options**, unselect **Precompiled header**.
+
+1. Choose **Finish** to create the solution and project.
+
+::: moniker-end
 
 ## Add the header and source file to the CodeDefects project
 
-1. In Solution Explorer, expand **CodeDefects**, right-click **Header Files**, click **Add**, and then click **New Item**.
+1. In Solution Explorer, expand **CodeDefects**.
 
-1. In the **Add New Item** dialog box, click **Code**, and then click **Header File (.h)**.
+1. Right-click to open the context menu for **Header Files**. Choose **Add** > **New Item**.
 
-1. In the **Name** box, type **Bug.h** and then click **Add**.
+1. In the **Add New Item** dialog box, select **Visual C++** > **Code**, and then select **Header File (.h)**.
+
+1. In the **Name** edit box, enter *Bug.h*, and then choose the **Add** button.
+
+1. In the edit window for *Bug.h*, select and delete the contents.
 
 1. Copy the following code and paste it into the *Bug.h* file in the editor.
 
@@ -58,9 +109,8 @@ The procedures also provide the code for the header and *.cpp* files for the sta
 
     #include <windows.h>
 
-    // These functions are consumed by the sample
-    // but are not defined. This project cannot be linked!
-    bool CheckDomain(LPCTSTR);
+    // Function prototypes
+    bool CheckDomain(wchar_t const *);
     HRESULT ReadUserAccount();
 
     // These constants define the common sizes of the
@@ -69,24 +119,34 @@ The procedures also provide the code for the header and *.cpp* files for the sta
     const int ACCOUNT_DOMAIN_LEN = 128;
     ```
 
-1. In Solution Explorer, right-click **Source Files**, point to **New**, and then click **New Item**.
+1. In Solution Explorer, right-click to open the context menu for **Source Files**. Choose **Add** > **New Item**.
 
-1. In the **Add New Item** dialog box, click **C++ File (.cpp)**
+1. In the **Add New Item** dialog box, select **C++ File (.cpp)**.
 
-1. In the **Name** box, type **Bug.cpp** and then click **Add**.
+1. In the **Name** edit box, enter *Bug.cpp*, and then choose the **Add** button.
 
 1. Copy the following code and paste it into the *Bug.cpp* file in the editor.
 
     ```cpp
     #include "Bug.h"
 
     // the user account
-    TCHAR g_userAccount[USER_ACCOUNT_LEN] = {};
+    wchar_t g_userAccount[USER_ACCOUNT_LEN] = { L"domain\\user" };
     int len = 0;
 
+    bool CheckDomain(wchar_t const* domain)
+    {
+        return (wcsnlen_s(domain, USER_ACCOUNT_LEN) > 0);
+    }
+
+    HRESULT ReadUserAccount()
+    {
+        return S_OK;
+    }
+
     bool ProcessDomain()
     {
-        TCHAR* domain = new TCHAR[ACCOUNT_DOMAIN_LEN];
+        wchar_t* domain = new wchar_t[ACCOUNT_DOMAIN_LEN];
         // ReadUserAccount gets a 'domain\user' input from
         //the user into the global 'g_userAccount'
         if (ReadUserAccount())
@@ -95,22 +155,22 @@ The procedures also provide the code for the header and *.cpp* files for the sta
             // character onto the 'domain' buffer
             for (len = 0; (len < ACCOUNT_DOMAIN_LEN) && (g_userAccount[len] != L'\0'); len++)
             {
-                if (g_userAccount[len] == '\\')
+                if (g_userAccount[len] == L'\\')
                 {
                     // Stops copying on the domain and user separator ('\')
                     break;
                 }
                 domain[len] = g_userAccount[len];
             }
-            if ((len = ACCOUNT_DOMAIN_LEN) || (g_userAccount[len] != '\\'))
+            if ((len = ACCOUNT_DOMAIN_LEN) || (g_userAccount[len] != L'\\'))
             {
                 // '\' was not found. Invalid domain\user string.
                 delete[] domain;
                 return false;
             }
             else
             {
-                domain[len] = '\0';
+                domain[len] = L'\0';
             }
             // Process domain string
             bool result = CheckDomain(domain);
@@ -133,31 +193,77 @@ The procedures also provide the code for the header and *.cpp* files for the sta
     }
     ```
 
-1. Click the **File** menu, and then click **Save All**.
+1. On the menu bar, choose **File** > **Save All**.
 
 ## Add the Annotations project and configure it as a static library
 
-1. In Solution Explorer, click **CppDemo**, point to **Add**, and then click **New Project**.
+::: moniker range=">=vs-2019"
+
+1. In Solution Explorer, right-click **CppDemo** to open the context menu. Choose **Add** > **New Project**.
+
+1. In the **Add a new project** dialog box, select **Windows Desktop Wizard**, and then choose the **Next** button.
+
+1. On the **Configure your new project** page, in the **Project name** text box, enter *Annotations*, and then choose **Create**.
+
+1. In the **Windows Desktop Project** dialog, change the **Application type** to **Static Library (.lib)**.
+
+1. Under **Additional options**, select **Empty project**.
+
+1. Choose **OK** to create the project.
+
+::: moniker-end
+
+::: moniker range="vs-2017"
+
+1. In Solution Explorer, right-click **CppDemo** to open the context menu. Choose **Add** > **New Project**.
+
+1. In the **Add New Project** dialog, select **Visual C++** > **Windows Desktop**.
+
+1. Select **Windows Desktop Wizard**.
+
+1. In the **Name** text box, enter *Annotations*, and then choose **OK**.
+
+1. In the **Windows Desktop Project** dialog, change the **Application type** to **Static Library (.lib)**.
+
+1. Under **Additional options**, select **Empty project**.
 
-1. In the **Add a new project** dialog box, Change language filter to **C++** and select **Empty Project** then click **Next**.
+1. Choose **OK** to create the project.
 
-1. In the **Project name** text box, type **Annotations**, and then click **Create**.
+::: moniker-end
 
-1. In Solution Explorer, right-click **Annotations** and then click **Properties**.
+::: moniker range="vs-2015"
 
-1. Expand **Configuration Properties** and then click **General**.
+1. In Solution Explorer, right-click **CppDemo** to open the context menu. Choose **Add** > **New Project**.
 
-1. In the **General** list, change **Configuration Type**, to and then click **Static library (.lib)**.
+1. In the **Add New Project** dialog, select **Visual C++** > **Win32**.
 
-1. In the **Advanced** list, select the text in the column next to **Target File extension**, and then type **.lib**.
+1. Select **Win32 Console Application**.
+
+1. In the **Name** text box, enter *Annotations*.
+
+1. Choose **OK**.
+
+1. In the **Win32 Application Wizard** dialog, choose the **Next** button.
+
+1. Change the **Application type** to **Static library**.
+
+1. Under **Additional options**, unselect **Precompiled header**.
+
+1. Choose **Finish** to create the project.
+
+::: moniker-end
 
 ## Add the header file and source file to the Annotations project
 
-1. In Solution Explorer, expand **Annotations**, right-click **Header Files**, click **Add**, and then click **New Item**.
+1. In Solution Explorer, expand **Annotations**.
+
+1. Right-click to open the context menu for **Header Files** under **Annotations**. Choose **Add** > **New Item**.
 
-1. In the **Add New Item** dialog box, click **Header File (.h)**.
+1. In the **Add New Item** dialog box, select **Visual C++** > **Code**, and then select **Header File (.h)**.
 
-1. In the **Name** box, type **annotations.h** and then click **Add**.
+1. In the **Name** edit box, enter *annotations.h*, and then choose the **Add** button.
+
+1. In the edit window for *annotations.h*, select and delete the contents.
 
 1. Copy the following code and paste it into the *annotations.h* file in the editor.
 
@@ -176,16 +282,23 @@ The procedures also provide the code for the header and *.cpp* files for the sta
     _Ret_maybenull_ LinkedList* AllocateNode();
     ```
 
-1. In Solution Explorer, right-click **Source Files**, point to **New**, and then click **New Item**.
+1. In Solution Explorer, right-click to open the context menu for **Source Files** under **Annotations**. Choose **Add** > **New Item**.
 
-1. In the **Add New Item** dialog box, click **Code** and then click **C++ File (.cpp)**
+1. In the **Add New Item** dialog box, select **C++ File (.cpp)**.
 
-1. In the **Name** box, type **annotations.cpp** and then click **Add**.
+1. In the **Name** edit box, enter *annotations.cpp*, and then choose the **Add** button.
 
 1. Copy the following code and paste it into the *annotations.cpp* file in the editor.
 
     ```cpp
     #include "annotations.h"
+    #include <malloc.h>
+
+    _Ret_maybenull_ LinkedList* AllocateNode()
+    {
+        LinkedList* result = static_cast<LinkedList*>(malloc(sizeof(LinkedList)));
+        return result;
+    }
 
     LinkedList* AddTail(LinkedList* node, int value)
     {
@@ -205,6 +318,13 @@ The procedures also provide the code for the header and *.cpp* files for the sta
     }
     ```
 
-1. Click the **File** menu, and then click **Save All**.
+1. On the menu bar, choose **File** > **Save All**.
 
 The solution is now complete and should build without errors.
+
+::: moniker range="vs-2017"
+
+> [!NOTE]
+> In Visual Studio 2017, you may see a spurious warning `E1097 unknown attribute "no_init_all"` in the IntelliSense engine. You can safely ignore this warning.
+
+::: moniker-end