Remaining open issues

- Fixes #43838: Add notes for collection expressions and using primary constructors. Include naming recommendations.
- Fixes #43839  Update the overview of constructors to include information on primary constructors.

Author: BillWagner

docs/csharp/fundamentals/coding-style/coding-conventions.md

@@ -1,7 +1,7 @@
 ---
 title: ".NET Coding Conventions"
 description: Learn about commonly used coding conventions in C#. Coding conventions create a consistent look to the code and facilitate copying, changing, and maintaining the code. This article also includes the docs repo coding guidelines
-ms.date: 01/14/2025
+ms.date: 01/15/2025
 helpviewer_keyword:
   - "coding conventions, C#"
   - "Visual C#, coding conventions"
@@ -42,13 +42,13 @@ Code analysis produces warnings and diagnostics when the enabled rules are viola
 The following sections describe practices that the .NET docs team follows to prepare code examples and samples. In general, follow these practices:
 
 - Utilize modern language features and C# versions whenever possible.
-- Avoid obsolete or outdated language constructs.
-- Only catch exceptions that can be properly handled; avoid catching generic exceptions.
+- Avoid outdated language constructs.
+- Only catch exceptions that can be properly handled; avoid catching general exceptions. For example, sample code should not catch the <xref:System.Exception?displayProperty=fullName> type without an exception filter.
 - Use specific exception types to provide meaningful error messages.
 - Use LINQ queries and methods for collection manipulation to improve code readability.
 - Use asynchronous programming with async and await for I/O-bound operations.
 - Be cautious of deadlocks and use <xref:System.Threading.Tasks.Task.ConfigureAwait%2A?DisplayProperty=nameWithType> when appropriate.
-- Use the language keywords for data types instead of the runtime types. For example, use `string` instead of <xref:System.String?DisplayProperty=fullName>, or `int` instead of <xref:System.Int32?displayProperty=fullName>.
+- Use the language keywords for data types instead of the runtime types. For example, use `string` instead of <xref:System.String?DisplayProperty=fullName>, or `int` instead of <xref:System.Int32?displayProperty=fullName>. This includes using the types `nint` and `nuint`.
 - Use `int` rather than unsigned types. The use of `int` is common throughout C#, and it's easier to interact with other libraries when you use `int`. Exceptions are for documentation specific to unsigned data types.
 - Use `var` only when a reader can infer the type from the expression. Readers view our samples on the docs platform. They don't have hover or tool tips that display the type of variables.
 - Write code with clarity and simplicity in mind.
@@ -66,15 +66,25 @@ More specific guidelines follow.
 
   :::code language="csharp" source="./snippets/coding-conventions/program.cs" id="Snippet7":::
 
-### Arrays
+- Prefer raw string literals to escape sequences or verbatim strings.
+- Use the expression based string interpolation rather than positional string interpolation.
 
-- Use the concise syntax when you initialize arrays on the declaration line. In the following example, you can't use `var` instead of `string[]`.
+### Constructors and initialization
 
-:::code language="csharp" source="./snippets/coding-conventions/program.cs" id="Snippet13a":::
+- Use Pascal case for primary constructor parameters on record types:
 
-- If you use explicit instantiation, you can use `var`.
+  :::code language="csharp" source="./snippets/coding-conventions/program.cs" id="PrimaryRecord":::
 
-:::code language="csharp" source="./snippets/coding-conventions/program.cs" id="Snippet13b":::
+- Use camel case for primary constructor parameters on class and struct types:
+- Prefer required `init` properties to constructors to initialize fields.
+
+  :::code language="csharp" source="./snippets/coding-conventions/program.cs" id="PrimaryClass":::
+
+### Arrays and collections
+
+- Use collection expressions to initialize all collection types
+
+:::code language="csharp" source="./snippets/coding-conventions/program.cs" id="Snippet13":::
 
 ### Delegates
 

docs/csharp/fundamentals/coding-style/snippets/coding-conventions/program.cs

@@ -61,16 +61,18 @@ static void Main(string[] args)
 
             // Save snippet 4 and 5 for possible additions in program structure.
 
-            Name[] nameList = {new Name { FirstName = "Anderson", LastName = "Redmond" },
-                                 new Name { FirstName = "Jones", LastName = "Seattle" },
-                                  new Name { FirstName = "Anderson", LastName = "Redmond" }};
+            Name[] nameList = [
+                new Name { FirstName = "Anderson", LastName = "Redmond" },
+                new Name { FirstName = "Jones", LastName = "Seattle" },
+                new Name { FirstName = "Anderson", LastName = "Redmond" }
+            ];
             int n = 0;
 
             //<snippet6>
             string displayName = $"{nameList[n].LastName}, {nameList[n].FirstName}";
             //</snippet6>
 
-            Console.WriteLine("{0}, {1}", nameList[n].LastName, nameList[n].FirstName);
+            Console.WriteLine($"{nameList[n].LastName}, {nameList[n].FirstName}");
             Console.WriteLine(nameList[n].LastName + ", " + nameList[n].FirstName);
 
             //<snippet7>
@@ -123,12 +125,9 @@ static void Main(string[] args)
             Console.WriteLine();
             //</snippet12>
 
-            //<snippet13a>
-            string[] vowels1 = { "a", "e", "i", "o", "u" };
-            //</snippet13a>
-            //<snippet13b>
-            var vowels2 = new string[] { "a", "e", "i", "o", "u" };
-            //</snippet13b>
+            //<snippet13>
+            string[] vowels = [ "a", "e", "i", "o", "u" ];
+            //</snippet13>
 
             //<snippet15b>
             Del exampleDel2 = DelMethod;
@@ -152,10 +151,7 @@ static void Main(string[] args)
             }
             finally
             {
-                if (bodyStyle != null)
-                {
-                    ((IDisposable)bodyStyle).Dispose();
-                }
+                bodyStyle?.Dispose();
             }
             //</snippet17a>
             //<snippet17b>
@@ -214,16 +210,10 @@ static void Main(string[] args)
 
             ExampleClass.totalInstances = 1;
 
-            var Customers = new List<Customer>
-            {
-              new Customer { Name = "Jones", ID = 432, City = "Redmond" }
-            };
+            List<Customer> Customers = [ new Customer { Name = "Jones", ID = 432, City = "Redmond" } ];
 
             // Check shop name to use this.
-            var Distributors = new List<Distributor>
-            {
-              new Distributor { Name = "ShopSmart", ID = 11302, City = "Redmond" }
-            };
+            List<Distributor> Distributors = [ new Distributor { Name = "ShopSmart", ID = 11302, City = "Redmond" } ];
 
             //<snippet25>
             //<snippet28>
@@ -335,20 +325,14 @@ public static int IncrementTotal()
             return totalInstances;
         }
 
-        public static int ResultSoFar()
-        {
-            return 0;
-        }
+        public static int ResultSoFar() => 0;
     }
 
     class BaseClass
     {
         protected static int totalInstances;
 
-        static BaseClass()
-        {
-            totalInstances = 0;
-        }
+        static BaseClass() => totalInstances = 0;
 
         public static int IncrementTotal()
         {
@@ -375,14 +359,13 @@ static void Main()
 
             // Use a collection initializer to create the data source. Note that
             // each element in the list contains an inner sequence of scores.
-            List<Student> students = new List<Student>
-        {
-           new Student {LastName="Omelchenko", Scores = [97, 72, 81, 60]},
-           new Student {LastName="O'Donnell", Scores = [75, 84, 91, 39]},
-           new Student {LastName="Mortensen", Scores = [88, 94, 65, 85]},
-           new Student {LastName="Garcia", Scores = [97, 89, 85, 82]},
-           new Student {LastName="Beebe", Scores = [35, 72, 91, 70]}
-        };
+            List<Student> students = [
+                new Student {LastName="Omelchenko", Scores = [97, 72, 81, 60]},
+                new Student {LastName="O'Donnell", Scores = [75, 84, 91, 39]},
+                new Student {LastName="Mortensen", Scores = [88, 94, 65, 85]},
+                new Student {LastName="Garcia", Scores = [97, 89, 85, 82]},
+                new Student {LastName="Beebe", Scores = [35, 72, 91, 70]}
+            ];
 
             //<snippet30>
             var scoreQuery = from student in students
@@ -395,12 +378,8 @@ where score > 90
             Console.WriteLine("scoreQuery:");
             foreach (var student in scoreQuery)
             {
-                Console.WriteLine("{0} Score: {1}", student.Last, student.score);
+                Console.WriteLine($"{student.Last} Score: {student.score}");
             }
-
-            // Keep the console window open in debug mode.
-            Console.WriteLine("Press any key to exit.");
-            Console.ReadKey();
         }
     }
 }
@@ -459,7 +438,7 @@ public class List<T> { /*...*/ }
         //</TypeParametersOne>
 
         //<TypeParametersTwo>
-        public int IComparer<T>() { return 0; }
+        public int IComparer<T>() => 0;
         public delegate bool Predicate<T>(T item);
         public struct Nullable<T> where T : struct { /*...*/ }
         //</TypeParametersTwo>
@@ -475,3 +454,22 @@ public interface ISessionChannel<TSession>
         }
     }//WrapParameters
 }
+
+namespace Constructors
+{
+    // <PrimaryRecord>
+    public record Person(string FirstName, string LastName);
+    // </PrimaryRecord>
+
+    // <PrimaryClass>
+    public class LabelledContainer<T>(string label)
+    {
+        public string Label { get; } = label;
+        public required T Contents 
+        { 
+            get;
+            init;
+        }
+    }
+    // </PrimaryClass>
+}

docs/csharp/programming-guide/classes-and-structs/constructors.md

@@ -1,15 +1,15 @@
 ---
 title: "Constructors"
 description: A constructor in C# is called when a class or struct is created. Use constructors to set defaults, limit instantiation, and write flexible, easy-to-read code.
-ms.date: 04/06/2023
+ms.date: 01/15/2025
 helpviewer_keywords: 
   - "constructors [C#]"
   - "classes [C#], constructors"
   - "C# language, constructors"
 ---
 # Constructors (C# programming guide)
 
-Whenever an instance of a [class](../../language-reference/keywords/class.md) or a [struct](../../language-reference/builtin-types/struct.md) is created, its constructor is called. A class or struct may have multiple constructors that take different arguments. Constructors enable the programmer to set default values, limit instantiation, and write code that is flexible and easy to read. For more information and examples, see [Instance constructors](instance-constructors.md) and [Using constructors](using-constructors.md).
+A *constructor* is a method that is called by the runtime when an instance of a [class](../../language-reference/keywords/class.md) or a [struct](../../language-reference/builtin-types/struct.md) is created. A class or struct may have multiple constructors that take different arguments. Constructors enable you to set ensure that instances of the type are valid when created. For more information and examples, see [Instance constructors](instance-constructors.md) and [Using constructors](using-constructors.md).
 
 There are several actions that are part of initializing a new instance. Those actions take place in the following order:
 
@@ -20,23 +20,27 @@ There are several actions that are part of initializing a new instance. Those ac
 1. *The instance constructor runs*. The instance constructor for the type runs.
 1. *Object initializers run*. If the expression includes any object initializers, those run after the instance constructor runs. Object initializers run in the textual order.
 
-The preceding actions take place when a new instance is initialized. If a new instance of a `struct` is set to its `default` value, all instance fields are set to 0.
+The preceding actions take place when an instance is created using the [`new` operator](../../language-reference//operators/new-operator.md). If a new instance of a `struct` is set to its `default` value, all instance fields are set to 0. Elements of an array are set to their default value of 0 or `null`.
 
 If the [static constructor](static-constructors.md) hasn't run, the static constructor runs before any of the instance constructor actions take place.
 
 ## Constructor syntax
 
-A constructor is a method whose name is the same as the name of its type. Its method signature includes only an optional [access modifier](./access-modifiers.md), the method name and its parameter list; it does not include a return type. The following example shows the constructor for a class named `Person`.
+A constructor is declared using the same as the name of its type. Its method signature can include an optional [access modifier](./access-modifiers.md), the method name and its parameter list; it does not include a return type. The following example shows the constructor for a class named `Person`.
 
 :::code source="./snippets/constructors/Program.cs" id="InstanceCtor":::
 
-If a constructor can be implemented as a single statement, you can use an [expression body definition](../statements-expressions-operators/expression-bodied-members.md). The following example defines a `Location` class whose constructor has a single string parameter named *name*. The expression body definition assigns the argument to the `locationName` field.
+If a constructor can be implemented as a single statement, you can use an [expression body member](../statements-expressions-operators/expression-bodied-members.md). The following example defines a `Location` class whose constructor has a single string parameter named *name*. The expression body definition assigns the argument to the `locationName` field.
 
 :::code source="./snippets/constructors/Program.cs" id="ExpressionBodiedCtor":::
 
+If a type requires a parameter to create an instance, you can use a *primary constructor* to indicate that one or more arguments are required to instantiate the type, as shown in the following example:
+
+:::code source="./snippets/constructors/Program.cs" id="PrimaryCtor":::
+
 ## Static constructors
 
-The previous examples have all shown instance constructors, which create a new object. A class or struct can also have a static constructor, which initializes static members of the type.  Static constructors are parameterless. If you don't provide a static constructor to initialize static fields, the C# compiler initializes static fields to their default value as listed in the [Default values of C# types](../../language-reference/builtin-types/default-values.md) article.
+The previous examples have shown instance constructors, which create a new object. A class or struct can also declare a static constructor, which initializes static members of the type.  Static constructors are parameterless. If you don't provide a static constructor to initialize static fields, the C# compiler initializes static fields to their default value as listed in the [Default values of C# types](../../language-reference/builtin-types/default-values.md) article.
 
 The following example uses a static constructor to initialize a static field.
 

docs/csharp/programming-guide/classes-and-structs/snippets/constructors/Program.cs

@@ -63,3 +63,15 @@ public string Name
 }
 // </ExpressionBodiedCtor>
 
+// <PrimaryCtor>
+public class LabelledContainer<T>(string label)
+{
+   public string Label { get; } = label;
+   public required T Contents 
+   { 
+      get;
+      init;
+   }
+}
+// </PrimaryCtor>
+