Merge pull request #10180 from MicrosoftDocs/main638479695457126698sync_temp

For protected branch, push strategy should use PR and merge to target branch method to work around git push error

Author: learn-build-service-prod[bot]

docs/ide/code-snippets.md

@@ -1,7 +1,7 @@
 ---
-title: Create and reuse code block snippets
-description: Explore code snippets, which are small blocks of reusable code that you can insert into a code file, such as `try-finally` or `if-else` blocks, classes, or methods.
-ms.date: 03/29/2024
+title: Understand and use code snippets
+description: Explore code snippets, which are small blocks of reusable code you can insert into a code file, and learn how to find and use them.
+ms.date: 04/05/2024
 ms.topic: conceptual
 f1_keywords:
 - vs.ExpansionManagerImport
@@ -19,36 +19,44 @@ dev_langs:
 - CPP
 ---
 
-# Code snippets: what they are and how to add one
+# Code snippets and how to use them
 
-Code snippets are small blocks of reusable code that you can add to a code file. Snippets most commonly contain often-used code blocks such as `try-finally` or `if-else` blocks. However, you can also use them to add entire classes or methods. Your snippets can even contain replacement parameters, which act as placeholders. Snippets are available for many languages, including C#, C++, and Visual Basic, to name a few.
+Code snippets are small blocks of reusable code that you can add to a code file. Snippets usually contain often-used code blocks such as `Try...Finally` or `If...Else` blocks. You can also use code snippets to add entire classes or methods.
+
+A code snippet has a title that you use to select the snippet, and can have a shortcut name you can type to insert the snippet. Snippets can also contain replacement parameters, which act as placeholders. Snippets are available for many languages, including C#, C++, and Visual Basic.
+
+## Expansion snippets and surround-with snippets
+
+You can add two kinds of code snippets to your code:
+
+- An *expansion* snippet is added at a specified insertion point.
+- A *surround-with* snippet is added around selected code, and is available only for C# and C++.
 
 ## Find available snippets
 
-Before you [create a snippet of your own](walkthrough-creating-a-code-snippet.md), you can check the available snippets for a language, select **Tools** > **Code Snippets Manager** from the menu bar (or, press **Ctrl**+**K**, **Ctrl**+**B**) and then select the language you want from the drop-down menu at the top of the dialog box.
+To view the available snippets for a language, select **Tools** > **Code Snippets Manager** from the menu bar, or press **Ctrl**+**K**, **B**, and then select the language you want from the dropdown menu.
 
 ![Screenshot of the Code Snippets Manager dialog box.](media/code-snippets-manager.png)
 
-## Add a snippet to your code file
+To create and import your own snippet so it appears in the snippet list, see [Walkthrough: Create a code snippet in Visual Studio](walkthrough-creating-a-code-snippet.md).
 
-In Visual Studio, there are several different ways you can add a code snippet to a code file:
+## Add a snippet to a code file
 
-- On the menu bar, choose **Edit** > **IntelliSense** > **Insert Snippet**
+To add a snippet to a code file:
 
-- From the right-click or context menu in the code editor, choose **Snippet** > **Insert Snippet**
+1. In the code editor, place your cursor or select C# or C++ code where you want to add the snippet.
 
-- From the keyboard, press **Ctrl**+**K**,**Ctrl**+**X**
+1. Take one of the following actions:
 
-## Expansion snippets and surround-with snippets
+   - On the Visual Studio menu bar, choose **Edit** > **IntelliSense** > **Insert Snippet** or **Edit** > **IntelliSense** > **Surround With**.
+   - Right-click, and choose **Snippet** > **Insert Snippet** or **Snippet** > **Surround With** from the context menu.
+   - From the keyboard, press **Ctrl**+**K**, **X** for an expansion snippet, or **Ctrl**+**K**, **S** for a surround-with snippet.
 
-There are two kinds of code snippets you can add to your code.
+1. Double-click the snippet you want in the dropdown list, or type the snippet shortcut and press **Tab**.
 
-|Snippet type  | How it's used  |
-|---------|---------|
-|*expansion* | Added at a specified insertion point and might replace a snippet shortcut |
-|*surround-with* | Added around a selected block of code (available for C# and C++ only) |
+### Add an expansion snippet
 
-In the following example of an expansion snippet in C#, the shortcut `tryf` adds a try-finally block:
+For example, the C# expansion snippet `tryf` adds the following `Try...Finally` block:
 
 ```csharp
 try
@@ -61,17 +69,18 @@ finally
 }
 ```
 
-Here's how to add this expansion snippet:
+To add this expansion snippet:
 
-1. In the code window, position your cursor where you want to add the snippet.
+1. In the code editor, position your cursor where you want to add the snippet.
+1. Right-click and select **Insert Snippet** from the right-click context menu, or use the menu bar or keyboard commands.
+1. Open the **Visual C#** folder, and then double-click **tryf** in the dropdown list, or select **tryf** and press **Tab**.
 
-1. Select **Insert Snippet** from the right-click context menu.
+>[!NOTE]
+>You can also place your cursor at the insertion point, type *tryf*, and then press **Tab** twice.
 
-   Alternatively, from the **Edit** menu, select **IntelliSense** and then select the **Surround With** command.
+### Add a surround-with snippet
 
-1. Select **Visual C#**, then type `tryf`, and then press **Tab**. (Or, you can type `tryf` and press **Tab** twice.)
-
-In the following example of a surround-with snippet in C++, the shortcut `if` can be used either as an insertion snippet or as a surround-with snippet. If you select a line of code (for example `return FALSE;`), and then choose **Surround With** > **if**, the snippet is expanded around the line:
+In the following example of a C++ snippet, the shortcut `if` can be used either as an insertion snippet or a surround-with snippet. If you select the code line `return FALSE;` and then choose **Surround With** > **if**, the snippet is expanded around the line.
 
 ```cpp
 if (true)
@@ -80,18 +89,11 @@ if (true)
 }
 ```
 
-::: moniker range="<=vs-2019"
-> [!TIP]
-> In Visual Studio 2019, you can use the **Ctrl**+**K**, **Ctrl**+**S** keyboard shortcut to insert a surround-with code snippet.
-::: moniker-end
-
 ## Snippet replacement parameters
 
-Snippets can contain replacement parameters, which are placeholders that you must replace to fit the code you're writing. In the previous example, `true` is a replacement parameter, which you'd replace with the appropriate condition. The replacement you make is repeated for every instance of the same replacement parameter in the snippet.
+Snippets can contain replacement parameters, which are placeholders you must replace to fit the code you're writing. In the previous example, `true` is a replacement parameter, which you replace with the appropriate condition. The replacement is repeated for every instance of that replacement parameter in the snippet.
 
-For example, in Visual Basic there's a code snippet that inserts a property. 
-
-To insert the snippet:
+For example, Visual Basic has a code snippet that defines a property. To insert the snippet:
 
 1. In the right-click context menu in a Visual Basic code file, select **Snippet** > **Insert Snippet**.
 2. Select **Code Patterns** > **Properties, Procedures, Events** > **Define a Property**.
@@ -112,63 +114,58 @@ Public Property NewProperty() As String
 End Property
 ```
 
-If you change `newPropertyValue` to `m_property`, then every instance of `newPropertyValue` is changed. If you change `String` to `Int` in the property declaration, then the value in the set method is also changed to `Int`.
+If you change `newPropertyValue` to `m_property`, every instance of `newPropertyValue` changes. If you change `String` to `Int` in the property declaration, the value in the `Set` method also changes to `Int`.
 
 ## Best practices for using code snippets
 
 The code in a code snippet shows only the most basic way to do something. For most applications, the code must be modified to suit the application.
 
-### Handling exceptions
+### Exception handling
 
-Typically, code snippet Try...Catch blocks catch and rethrow all exceptions. That may not be the right choice for your project. For each exception, there are several ways to respond. For examples, see [How to: Handle an exception using try/catch (C#)](/dotnet/csharp/programming-guide/exceptions/how-to-handle-an-exception-using-try-catch) and [Try...Catch...Finally statement (Visual Basic)](/dotnet/visual-basic/language-reference/statements/try-catch-finally-statement).
+Typically, code snippet `Try...Catch` blocks catch and rethrow all exceptions, but that might not be the right choice for your project. For each exception, there are several ways to respond. For examples, see [How to handle an exception using try/catch (C#)](/dotnet/csharp/programming-guide/exceptions/how-to-handle-an-exception-using-try-catch) and [Try...Catch...Finally statement (Visual Basic)](/dotnet/visual-basic/language-reference/statements/try-catch-finally-statement).
 
 ### File locations
 
-When you adapt file locations to your application, you should think about the following:
+When you adapt file locations to your application, be sure to consider the following factors.
+
+- Find an accessible location. Users might not have access to the computer's *Program Files* folder, so storing user files with the application files might not work.
 
-- Finding an accessible location. Users may not have access to the *Program Files* folder of the computer, so storing files with the application files may not work.
+- Find a secure location. Storing files in the root folder like *C:\\* isn't secure. For application data, it's best to use the *Application Data* folder. For individual user data, the application can create a file in each user's *Documents* folder.
 
-- Finding a secure location. Storing files in the root folder (*C:\\*) is not secure. For application data, we recommend the *Application Data* folder. For individual user data, the application can create a file for each user in the *Documents* folder.
+- Use a valid file name. You can use the <xref:System.Windows.Forms.OpenFileDialog> and <xref:System.Windows.Forms.SaveFileDialog> controls to reduce the likelihood of invalid file names.
 
-- Using a valid file name. You can use the <xref:System.Windows.Forms.OpenFileDialog> and <xref:System.Windows.Forms.SaveFileDialog> controls to reduce the likelihood of invalid file names. Be aware that between the time the user selects a file and the time your code manipulates the file, the file may be deleted. In addition, the user may not have permissions to write to the file.
+- Be aware that a user-selected file could be deleted before your code can manipulate the file. Also, a user might not have permission to write to the file.
 
 ### Security
 
-How secure a snippet is depends on where it is used in the source code and how it is modified once it is in the code. The following list contains a few of the areas that must be considered.
+The security of a snippet depends on where you use it in the source code and how you modify it once it's in the code. The following list contains a few areas to consider:
 
 - File and database access
-
 - Code access security
-
-- Protecting resources (such as event logs, registry)
-
+- Protecting resources such as event logs and registry
 - Storing secrets
-
 - Verifying inputs
-
 - Passing data to scripting technologies
 
-For more information, see [Securing applications](../ide/securing-applications.md).
+For more information, see [Secure applications](securing-applications.md).
 
 ### Downloaded code snippets
 
-Code snippets installed by Visual Studio are not in themselves a security hazard. However, they can create security risks in your application. Snippets downloaded from the Internet should be treated like any other downloaded content - with extreme caution.
-
-- Download snippets only from sites you trust, and use up-to-date virus software.
+Code snippets installed by Visual Studio aren't security hazards themselves. However, they can create security risks in your application. Snippets downloaded from the internet should be treated with extreme caution, like any other downloaded content. Download snippets only from sites you trust, and use up-to-date virus software.
 
-- Open all downloaded snippet files in Notepad or the XML editor of Visual Studio and review them carefully before installing them. Look for the following issues:
+Open all downloaded snippet files in Notepad or the XML editor of Visual Studio and review them carefully before installing them. Beware of the following issues:
 
-  - The snippet code could damage your system if you execute it. Read the source code carefully before running it.
+  - Snippet code that could damage your system if you execute it. Read the source code carefully before running it.
 
-  - The Help URL block of the snippet file can contain URLs that execute a malicious script file or display an offensive website.
+  - `HelpURL` blocks in snippet files containing URLs that execute malicious script files or display offensive websites.
 
-  - The snippet may contain references that are added silently to your project and may be loaded from anywhere on your system. These references may have been downloaded to your computer from where you downloaded the snippet. The snippet may then make a call to a method in the reference that executes malicious code. To protect yourself against such an attack, review the Imports and References blocks of the snippet file.
+  - Snippets containing references that are added silently to your project and can be loaded from anywhere on your system. You might download these references from the same location you download a snippet from. The snippet could then call a method in the reference that executes malicious code. To detect such references, review the `Imports` and `References` blocks of the snippet file.
 
 ## Related content
 
-- [Create a code snippet](walkthrough-creating-a-code-snippet.md).
-- [Distribute code snippets](how-to-distribute-code-snippets.md)
+- [Walkthrough: Create a code snippet in Visual Studio](walkthrough-creating-a-code-snippet.md)
+- [Distribute code snippets as a Visual Studio extension](how-to-distribute-code-snippets.md)
 - [C# code snippets](visual-csharp-code-snippets.md)
-- [C++ code snippets](visual-cpp-code-snippets.md)
+- [Visual C++ code snippets](visual-cpp-code-snippets.md)
 - [Code snippets schema reference](code-snippets-schema-reference.md)