Skip to content

Clarify Components code documentation guidance #68345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PureWeen merged 2 commits into from
Aug 11, 2026
Merged

Clarify Components code documentation guidance #68345

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d2dde8c
Clarify Components code documentation guidance
Copilot Aug 11, 2026
b5e6c36
Refine Components XML documentation guidance
Copilot Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions src/Components/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,18 @@ 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 internal implementation details,
including control flow or lifecycle state. Limit it to consumer-observable behavior.

### Overview

The workflow for implementing new features in the Components area follows these steps:
Expand Down
Loading