Clarify with initialization order (#47977)

* Clarify `with` initialization order

Fixes #47503

In articles where `record` and `with` expressions are explained, add details about the order of initialization and with expressions. Provide guidance to compute the property value on access, not initialization.

* Grammar pass + build issues

* Apply suggestions from code review

Co-authored-by: Genevieve Warren <[email protected]>

---------

Co-authored-by: Genevieve Warren <[email protected]>

Author: BillWagner

docs/csharp/fundamentals/types/records.md

@@ -1,7 +1,7 @@
 ---
 title: "Record types"
 description: Learn about C# record types and how to create them. A record is a class that provides value semantics.
-ms.date: 05/24/2023
+ms.date: 08/15/2025
 helpviewer_keywords: 
   - "records [C#]"
   - "C# language, records"
@@ -31,7 +31,7 @@ Immutability isn't appropriate for all data scenarios. [Entity Framework Core](/
 
 ## How records differ from classes and structs
 
-The same syntax that [declares](classes.md#declaring-classes) and [instantiates](classes.md#creating-objects) classes or structs can be used with records. Just substitute the `class` keyword with the `record`, or use `record struct` instead of `struct`. Likewise, the same syntax for expressing inheritance relationships is supported by record classes. Records differ from classes in the following ways:
+The same syntax that [declares](classes.md#declaring-classes) and [instantiates](classes.md#creating-objects) classes or structs can be used with records. Just substitute the `class` keyword with the `record`, or use `record struct` instead of `struct`. Likewise, record classes support the same syntax for expressing inheritance relationships. Records differ from classes in the following ways:
 
 * You can use [positional parameters](../../language-reference/builtin-types/record.md#positional-syntax-for-property-and-field-definition) in a [primary constructor](../../programming-guide/classes-and-structs/instance-constructors.md#primary-constructors) to create and instantiate a type with immutable properties.
 * The same methods and operators that indicate reference equality or inequality in classes (such as <xref:System.Object.Equals(System.Object)?displayProperty=nameWithType> and `==`), indicate [value equality or inequality](../../language-reference/builtin-types/record.md#value-equality) in records.
@@ -57,6 +57,8 @@ The following example demonstrates use of a `with` expression to copy an immutab
 
 :::code language="csharp" source="./snippets/records/ImmutableRecord.cs" id="ImmutableRecord":::
 
+In the preceding examples, all properties are independent. None of the properties are computed from other property values. A `with` expression first copies the existing record instance, then modifies any properties or fields specified in the `with` expression. Computed properties in `record` types should be computed on access, not initialized when the instance is created. Otherwise, a property could return the computed value based on the original instance, not the modified copy. If you must initialize a computed property rather than compute on access, you should consider a [`class`](./classes.md) instead of a record.
+
 For more information, see [Records (C# reference)](../../language-reference/builtin-types/record.md).
 
 ## C# Language Specification

docs/csharp/language-reference/builtin-types/record.md

@@ -1,7 +1,7 @@
 ---
 title: "Records"
 description: Learn about the record modifier for class and struct types in C#. Records provide standard support for value based equality on instances of record types.
-ms.date: 02/05/2025
+ms.date: 08/15/2025
 f1_keywords: 
   - "record_CSharpKeyword"
 helpviewer_keywords: 
@@ -146,6 +146,27 @@ If you need different copying behavior, you can write your own copy constructor
 
 You can't override the clone method, and you can't create a member named `Clone` in any record type. The actual name of the clone method is compiler-generated.
 
+> [!IMPORTANT]
+> In the preceding examples, all properties are independent. None of the properties are computed from other property values. A `with` expression first copies the existing record instance, then modifies any properties or fields specified in the `with` expression. Computed properties in `record` types should be computed on access, not initialized when the instance is created. Otherwise, a property could return the computed value based on the original instance, not the modified copy.
+
+You ensure correctness on computed properties by computing the value on access, as shown in the following declaration:
+
+:::code language="csharp" source="snippets/shared/RecordType.cs" id="WitherComputed":::
+
+The preceding record type computes the `Distance` when accessed, as shown in the following example:
+
+:::code language="csharp" source="snippets/shared/RecordType.cs" id="WitherComputedUsage":::
+
+Contrast that with the following declaration, where the `Distance` property is computed and cached as part of the initialization of a new instance:
+
+:::code language="csharp" source="snippets/shared/RecordType.cs" id="WitherInit":::
+
+Because `Distance` is computed as part of initialization, the value is computed and cached before the `with` expression changes the value of `Y` in the copy. The result is that the distance is incorrect:
+
+:::code language="csharp" source="snippets/shared/RecordType.cs" id="WitherInitUsage":::
+
+The `Distance` computation isn't expensive to compute on each access. However, some computed properties might require access to more data or more extensive computation. In those cases, instead of a record, use a `class` type and compute the cached value when one of the components changes value.
+
 ## Built-in formatting for display
 
 Record types have a compiler-generated <xref:System.Object.ToString%2A> method that displays the names and values of public properties and fields. The `ToString` method returns a string of the following format:

docs/csharp/language-reference/builtin-types/snippets/shared/RecordType.cs

@@ -23,6 +23,9 @@ public static void Examples()
             var p = new Point();
             (double x, double y, double z) = p;
 
+            Console.WriteLine("=================================================");
+            ComputedWither.ExampleUsage.Example();
+
         }
         // <PositionalRecord>
         public record Person(string FirstName, string LastName);
@@ -102,7 +105,7 @@ public static class PositionalAttributes
         /// map to the JSON elements "firstName" and "lastName" when
         /// serialized or deserialized.
         /// </remarks>
-        public record Person([property: JsonPropertyName("firstName")] string FirstName, 
+        public record Person([property: JsonPropertyName("firstName")] string FirstName,
             [property: JsonPropertyName("lastName")] string LastName);
         // </PositionalAttributes>
 
@@ -335,7 +338,8 @@ protected override bool PrintMembers(StringBuilder stringBuilder)
                     if (base.PrintMembers(stringBuilder))
                     {
                         stringBuilder.Append(", ");
-                    };
+                    }
+                    ;
                     stringBuilder.Append($"Grade = {Grade}");
                     return true;
                 }
@@ -426,4 +430,47 @@ public static void Main()
             // </WithExpressionInheritance>
         }
     }
+
+    namespace ComputedWither
+    {
+        // <WitherComputed>
+        public record Point(int X, int Y)
+        {
+            public double Distance => Math.Sqrt(X * X + Y * Y);
+        }
+        // </WitherComputed>
+
+        // <WitherInit>
+        public record PointInit(int X, int Y)
+        {
+            public double Distance { get; } = Math.Sqrt(X * X + Y * Y);
+        }
+        // </WitherInit>
+
+        public static class ExampleUsage
+        {
+            public static void Example()
+            {
+                // <WitherComputedUsage>
+                Point p1 = new Point(3, 4);
+                Console.WriteLine($"Original point: {p1}");
+                p1 = p1 with { Y = 8 };
+                Console.WriteLine($"Modified point: {p1}");
+                // Output:
+                // Original point: Point { X = 3, Y = 4, Distance = 5 }
+                // Modified point: Point { X = 3, Y = 8, Distance = 8.54400374531753 }
+                // </WitherComputedUsage>
+
+                // <WitherInitUsage>
+                PointInit pt1 = new PointInit(3, 4);
+                Console.WriteLine($"Original point: {pt1}");
+                pt1 = pt1 with { Y = 8 };
+                Console.WriteLine($"Incorrect Modified point: {pt1}");
+                // Output:
+                // Original point: PointInit { X = 3, Y = 4, Distance = 5 }
+                // Modified point: PointInit { X = 3, Y = 8, Distance = 5 }
+                // </WitherInitUsage>
+            }
+        }
+    }
 }

docs/csharp/language-reference/operators/with-expression.md

@@ -1,14 +1,14 @@
 ---
-title: "with expression - create new objects that are modified copies of existing objects"
+title: "The with expression - create new objects that are modified copies of existing objects"
 description: "Learn about a with expression that performs nondestructive mutation of C# records and structures. The `with` keyword provides the means to modify one or more properties in the new object."
-ms.date: 11/22/2024
+ms.date: 08/15/2025
 f1_keywords:
   - "with_CSharpKeyword"
 helpviewer_keywords:
   - "with expression [C#]"
   - "with operator [C#]"
 ---
-# with expression - Nondestructive mutation creates a new object with modified properties
+# The `with` expression - Nondestructive mutation creates a new object with modified properties
 
 A `with` expression produces a copy of its operand with the specified properties and fields modified. You use the [object initializer](../../programming-guide/classes-and-structs/object-and-collection-initializers.md) syntax to specify what members to modify and their new values:
 
@@ -20,7 +20,7 @@ The result of a `with` expression has the same run-time type as the expression's
 
 :::code language="csharp" source="snippets/with-expression/InheritanceExample.cs" :::
 
-In the case of a reference-type member, only the reference to a member instance is copied when an operand is copied. Both the copy and original operand have access to the same reference-type instance. The following example demonstrates that behavior:
+When a member is a reference type, only the reference to a member instance is copied when an operand is copied. Both the copy and original operand have access to the same reference-type instance. The following example demonstrates that behavior:
 
 :::code language="csharp" source="snippets/with-expression/ExampleWithReferenceType.cs" :::
 
@@ -32,6 +32,9 @@ Any record class type has the *copy constructor*. A *copy constructor* is a cons
 
 You can't customize the copy semantics for structure types.
 
+> [!IMPORTANT]
+> In the preceding examples, all properties are independent. None of the properties are computed from other property values. A `with` expression first copies the existing record instance, then modifies any properties or fields specified in the `with` expression. Computed properties in `record` types should be computed on access, not initialized when the instance is created. Otherwise, a property could return the computed value based on the original instance, not the modified copy. For more information, see the language reference article on [`record` types](../builtin-types/record.md#nondestructive-mutation).
+
 ## C# language specification
 
 For more information, see the following sections of the [records feature proposal note](~/_csharplang/proposals/csharp-9.0/records.md):