[matt-edmondson]

Fixes #117

What changed

The README's OptimizedObject example cached _resource.DeepClone() and handed that one instance to every clone. As a result:

• all clones shared a single mutable resource, so an edit through one clone showed up in all the later ones;
• in-place edits to the original were never cloned, because only the setter cleared the cache.

I took the "share only when truly immutable, and say so" option:

• Example. The expensive resource is now an immutable LookupTable with read-only members holding only an ImmutableArray<int>, and it is shared by reference. The mutable state (Scratch) is cloned on every call. A closing note says to build a new table to change it, and to clone the resource on every call if it has to stay mutable.
• Tip 1 ("Lazy Clone When Possible") is now "Share Immutable Data Instead of Cloning It".
• Tip 3 ("Consider Caching") is now "Never Share or Cache Clones of Mutable Data", with the reason.

About the acceptance check: ReferenceEquals(a.Table, b.Table) is true by design, because the shared object is immutable. No edit can be made through it, so nothing can leak between clones. All mutable state in the example gets a fresh copy (ReferenceEquals(a.Scratch, b.Scratch) == false).

Tests

ReadmePerformanceExampleTests:

• OptimizedObject_Clones_AreIndependentOfEachOther runs the issue's repro against the new example. It checks that an edit through clone a doesn't reach clone b, that a clone taken after editing the original in place picks up the edit, and that replacing Table on one clone leaves the others alone.
• Readme_ShowsTheTestedExample and Readme_DoesNotCacheAClonedMutableResource check that the README shows the tested example and no longer shows the _clonedResource cache. On main, 5 of these cases fail. With this change they pass. I checked that by stashing the README change and running them again.

Full suite: 72/72 passing on net10.0.

Related: #122 (README inheritance sample, #104) touches a different section of README.md. The two PRs are independent and don't conflict.

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud