update ca1814 description (#22088)

gewarren · web-flow · commit fd1beae06f20 · 2020-12-21T08:31:41.000-08:00
diff --git a/docs/csharp/programming-guide/arrays/jagged-arrays.md b/docs/csharp/programming-guide/arrays/jagged-arrays.md
@@ -1,64 +1,64 @@
 ---
-title: "Jagged Arrays - C# Programming Guide"
-description: A jagged array in C# is an array whose elements are arrays of different dimensions and sizes. Learn how to declare, initialize, and access jagged arrays.
-ms.date: 07/20/2015
-helpviewer_keywords: 
+title: Jagged Arrays - C# Programming Guide
+description: A jagged array in C# is an array whose elements are arrays of different sizes. Learn how to declare, initialize, and access jagged arrays.
+ms.date: 12/18/2020
+helpviewer_keywords:
   - "jagged arrays [C#]"
   - "arrays [C#], jagged"
 ms.assetid: 537c65a6-0e0a-4a00-a2b8-086f38519c70
 ---
 # Jagged Arrays (C# Programming Guide)
 
-A jagged array is an array whose elements are arrays. The elements of a jagged array can be of different dimensions and sizes. A jagged array is sometimes called an "array of arrays." The following examples show how to declare, initialize, and access jagged arrays.  
-  
- The following is a declaration of a single-dimensional array that has three elements, each of which is a single-dimensional array of integers:  
-  
- [!code-csharp[csProgGuideArrays#19](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#19)]  
-  
- Before you can use `jaggedArray`, its elements must be initialized. You can initialize the elements like this:  
-  
- [!code-csharp[csProgGuideArrays#20](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#20)]  
-  
- Each of the elements is a single-dimensional array of integers. The first element is an array of 5 integers, the second is an array of 4 integers, and the third is an array of 2 integers.  
-  
- It is also possible to use initializers to fill the array elements with values, in which case you do not need the array size. For example:  
-  
- [!code-csharp[csProgGuideArrays#21](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#21)]  
-  
- You can also initialize the array upon declaration like this:  
-  
- [!code-csharp[csProgGuideArrays#22](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#22)]  
-  
- You can use the following shorthand form. Notice that you cannot omit the `new` operator from the elements initialization because there is no default initialization for the elements:  
-  
- [!code-csharp[csProgGuideArrays#23](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#23)]  
-  
- A jagged array is an array of arrays, and therefore its elements are reference types and are initialized to `null`.  
-  
- You can access individual array elements like these examples:  
-  
- [!code-csharp[csProgGuideArrays#24](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#24)]  
-  
- It is possible to mix jagged and multidimensional arrays. The following is a declaration and initialization of a single-dimensional jagged array that contains three two-dimensional array elements of different sizes. For more information about two-dimensional arrays, see [Multidimensional Arrays](./multidimensional-arrays.md).  
-  
- [!code-csharp[csProgGuideArrays#25](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#25)]  
-  
- You can access individual elements as shown in this example, which displays the value of the element `[1,0]` of the first array (value `5`):  
-  
- [!code-csharp[csProgGuideArrays#26](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#26)]  
-  
- The method `Length` returns the number of arrays contained in the jagged array. For example, assuming you have declared the previous array, this line:  
-  
- [!code-csharp[csProgGuideArrays#27](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#27)]  
-  
- returns a value of 3.  
-  
+A jagged array is an array whose elements are arrays, possibly of different sizes. A jagged array is sometimes called an "array of arrays." The following examples show how to declare, initialize, and access jagged arrays.
+
+ The following is a declaration of a single-dimensional array that has three elements, each of which is a single-dimensional array of integers:
+
+ [!code-csharp[csProgGuideArrays#19](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#19)]
+
+ Before you can use `jaggedArray`, its elements must be initialized. You can initialize the elements like this:
+
+ [!code-csharp[csProgGuideArrays#20](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#20)]
+
+ Each of the elements is a single-dimensional array of integers. The first element is an array of 5 integers, the second is an array of 4 integers, and the third is an array of 2 integers.
+
+ It is also possible to use initializers to fill the array elements with values, in which case you do not need the array size. For example:
+
+ [!code-csharp[csProgGuideArrays#21](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#21)]
+
+ You can also initialize the array upon declaration like this:
+
+ [!code-csharp[csProgGuideArrays#22](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#22)]
+
+ You can use the following shorthand form. Notice that you cannot omit the `new` operator from the elements initialization because there is no default initialization for the elements:
+
+ [!code-csharp[csProgGuideArrays#23](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#23)]
+
+ A jagged array is an array of arrays, and therefore its elements are reference types and are initialized to `null`.
+
+ You can access individual array elements like these examples:
+
+ [!code-csharp[csProgGuideArrays#24](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#24)]
+
+ It's possible to mix jagged and multidimensional arrays. The following is a declaration and initialization of a single-dimensional jagged array that contains three two-dimensional array elements of different sizes. For more information, see [Multidimensional Arrays](./multidimensional-arrays.md).
+
+ [!code-csharp[csProgGuideArrays#25](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#25)]
+
+ You can access individual elements as shown in this example, which displays the value of the element `[1,0]` of the first array (value `5`):
+
+ [!code-csharp[csProgGuideArrays#26](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#26)]
+
+ The method `Length` returns the number of arrays contained in the jagged array. For example, assuming you have declared the previous array, this line:
+
+ [!code-csharp[csProgGuideArrays#27](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#27)]
+
+ returns a value of 3.
+
 ## Example
 
- This example builds an array whose elements are themselves arrays. Each one of the array elements has a different size.  
-  
- [!code-csharp[csProgGuideArrays#18](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#18)]  
-  
+ This example builds an array whose elements are themselves arrays. Each one of the array elements has a different size.
+
+ [!code-csharp[csProgGuideArrays#18](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs#18)]
+
 ## See also
 
 - <xref:System.Array>
diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1814.md b/docs/fundamentals/code-analysis/quality-rules/ca1814.md
@@ -1,7 +1,7 @@
 ---
 title: "CA1814: Prefer jagged arrays over multidimensional (code analysis)"
 description: "Learn about code analysis rule CA1814: Prefer jagged arrays over multidimensional"
-ms.date: 11/04/2016
+ms.date: 12/18/2020
 ms.topic: reference
 f1_keywords:
 - PreferJaggedArraysOverMultidimensional
@@ -25,19 +25,19 @@ dev_langs:
 
 ## Cause
 
-A member is declared as a multidimensional array.
+A member is declared as a multidimensional array, which can result in wasted space for some data sets.
 
 ## Rule description
 
-A jagged array is an array whose elements are arrays. The arrays that make up the elements can be of different sizes, leading to less wasted space for some sets of data.
+In a [multidimensional array](../../../csharp/programming-guide/arrays/multidimensional-arrays.md), each element in each dimension has the same, fixed size as the other elements in that dimension. In a [jagged array](../../../csharp/programming-guide/arrays/jagged-arrays.md), which is an array of arrays, each inner array can be of a different size. By only using the space that's needed for a given array, no space is wasted. This rule, CA1814, recommends switching to a jagged array to conserve memory.
 
 ## How to fix violations
 
 To fix a violation of this rule, change the multidimensional array to a jagged array.
 
 ## When to suppress warnings
 
-Suppress a warning from this rule if the multidimensional array does not waste space.
+It's okay to suppress a warning from this rule if the multidimensional array does not waste space.
 
 ## Example
 
diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.cs
@@ -32,10 +32,10 @@ static void Main()
         System.Console.ReadKey();
     }
 }
-    /* Output:
-        Array elements are:
-        1111 2 3 4 5555
-    */
+/* Output:
+    Array elements are:
+    1111 2 3 4 5555
+*/
 //</Snippet38>
 
 //<Snippet37>
@@ -66,10 +66,10 @@ static void Main()
         System.Console.ReadKey();
     }
 }
-    /* Output:
-        Array elements are:
-        1 2 3 4 5
-    */
+/* Output:
+    Array elements are:
+    1 2 3 4 5
+*/
 //</Snippet37>
 
 class TestPrintArray1D
@@ -98,7 +98,7 @@ void Test()
 
 class TestPrintArray2D
 {
-    int[,] theArray =  { { 1, 2 }, { 2, 3 }, { 3, 4 } };
+    int[,] theArray = { { 1, 2 }, { 2, 3 }, { 3, 4 } };
 
     //<Snippet36>
     void Print2DArray(int[,] arr)
@@ -142,16 +142,16 @@ static void Main()
         System.Console.ReadKey();
     }
 }
-    /* Output:
-        Element(0,0)=1
-        Element(0,1)=2
-        Element(1,0)=3
-        Element(1,1)=4
-        Element(2,0)=5
-        Element(2,1)=6
-        Element(3,0)=7
-        Element(3,1)=8
-    */
+/* Output:
+    Element(0,0)=1
+    Element(0,1)=2
+    Element(1,0)=3
+    Element(1,1)=4
+    Element(2,0)=5
+    Element(2,1)=6
+    Element(3,0)=7
+    Element(3,1)=8
+*/
 //</Snippet31>
 
 class Test3
@@ -165,7 +165,7 @@ static void Main()
             System.Console.Write("{0} ", i);
         }
         // Output: 4 5 6 1 2 3 -2 -1 0
-         //</Snippet28>
+        //</Snippet28>
 
         System.Console.WriteLine();
 
@@ -221,7 +221,7 @@ void test()
         //</Snippet11>
 
         //<Snippet12>
-        int[, ,] array1 = new int[4, 2, 3];
+        int[,,] array1 = new int[4, 2, 3];
         //</Snippet12>
 
         //<Snippet13>
@@ -234,10 +234,10 @@ void test()
                                                 { "five", "six" } };
 
         // Three-dimensional array.
-        int[, ,] array3D = new int[,,] { { { 1, 2, 3 }, { 4, 5, 6 } },
+        int[,,] array3D = new int[,,] { { { 1, 2, 3 }, { 4, 5, 6 } },
                                          { { 7, 8, 9 }, { 10, 11, 12 } } };
         // The same array with dimensions specified.
-        int[, ,] array3Da = new int[2, 2, 3] { { { 1, 2, 3 }, { 4, 5, 6 } },
+        int[,,] array3Da = new int[2, 2, 3] { { { 1, 2, 3 }, { 4, 5, 6 } },
                                                { { 7, 8, 9 }, { 10, 11, 12 } } };
 
         // Accessing array elements.
@@ -253,7 +253,8 @@ void test()
         // Getting the total count of elements or the length of a given dimension.
         var allLength = array3D.Length;
         var total = 1;
-        for (int i = 0; i < array3D.Rank; i++) {
+        for (int i = 0; i < array3D.Rank; i++)
+        {
             total *= array3D.GetLength(i);
         }
         System.Console.WriteLine("{0} equals {1}", allLength, total);
@@ -395,21 +396,21 @@ void test()
         //</Snippet21>
 
         //<Snippet22>
-    int[][] jaggedArray2 = new int[][]
-    {
+        int[][] jaggedArray2 = new int[][]
+        {
         new int[] { 1, 3, 5, 7, 9 },
         new int[] { 0, 2, 4, 6 },
         new int[] { 11, 22 }
-    };
+        };
         //</Snippet22>
 
         //<Snippet23>
-    int[][] jaggedArray3 =
-    {
-        new int[] { 1, 3, 5, 7, 9 },
-        new int[] { 0, 2, 4, 6 },
-        new int[] { 11, 22 }
-    };
+        int[][] jaggedArray3 =
+        {
+            new int[] { 1, 3, 5, 7, 9 },
+            new int[] { 0, 2, 4, 6 },
+            new int[] { 11, 22 }
+        };
         //</Snippet23>
 
         //<Snippet24>
diff --git a/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.csproj b/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideArrays/CS/Arrays.csproj
@@ -0,0 +1,7 @@
+﻿<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>netstandard2.1</TargetFramework>
+  </PropertyGroup>
+
+</Project>
