From d2dde8c2ec69afdd64a8b435c3282032db60a3a3 Mon Sep 17 00:00:00 2001 From: PureWeen <223556219+Copilot@users.noreply.github.com> Date: Tue, 11 Aug 2026 09:21:28 -0500 Subject: [PATCH 1/2] Clarify Components code documentation guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0fb5ea3b-44bb-495b-99c5-93e753ca9ce1 --- src/Components/AGENTS.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/Components/AGENTS.md b/src/Components/AGENTS.md index 42902151c4b6..fa932b5b0028 100644 --- a/src/Components/AGENTS.md +++ b/src/Components/AGENTS.md @@ -18,6 +18,19 @@ You MUST follow this workflow when implementing new features or fixing bugs in t - Only after the E2E tests are passing, remove the sample code you added in the Samples projects. - Use `git checkout` and `git clean -fd` to remove the sample code. +### Code clarity and durable knowledge + +- Before adding a comment, make local behavior discoverable through precise names, + named methods or variables, and smaller single-purpose responsibilities. A named + method can improve clarity even when it does not reduce duplication. +- Add a concise implementation comment only when a durable nonlocal reason cannot + be expressed by structure alone, such as ordering across JavaScript and .NET + callbacks, lifecycle ownership transfer, compatibility constraints, or a + required negative guarantee. Do not narrate the call graph or restate the code. +- Do not use public XML documentation to explain private implementation mechanics, + control flow, or lifecycle state. Limit it to consumer-observable behavior, and + encode executable invariants in focused tests. + ### Overview The workflow for implementing new features in the Components area follows these steps: From b5e6c36a53db865f5cef1b54145e5c3cbfe35648 Mon Sep 17 00:00:00 2001 From: PureWeen <223556219+Copilot@users.noreply.github.com> Date: Tue, 11 Aug 2026 09:39:13 -0500 Subject: [PATCH 2/2] Refine Components XML documentation guidance Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 0fb5ea3b-44bb-495b-99c5-93e753ca9ce1 --- src/Components/AGENTS.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/Components/AGENTS.md b/src/Components/AGENTS.md index fa932b5b0028..fd579b2a3447 100644 --- a/src/Components/AGENTS.md +++ b/src/Components/AGENTS.md @@ -27,9 +27,8 @@ You MUST follow this workflow when implementing new features or fixing bugs in t be expressed by structure alone, such as ordering across JavaScript and .NET callbacks, lifecycle ownership transfer, compatibility constraints, or a required negative guarantee. Do not narrate the call graph or restate the code. -- Do not use public XML documentation to explain private implementation mechanics, - control flow, or lifecycle state. Limit it to consumer-observable behavior, and - encode executable invariants in focused tests. +- Do not use public XML documentation to explain internal implementation details, + including control flow or lifecycle state. Limit it to consumer-observable behavior. ### Overview