Skip to content

Clarify Components code documentation guidance - #68345

Merged
PureWeen merged 2 commits into
dotnet:mainfrom
PureWeen:pureween-clarify-components-guidance
Aug 11, 2026
Merged

Clarify Components code documentation guidance#68345
PureWeen merged 2 commits into
dotnet:mainfrom
PureWeen:pureween-clarify-components-guidance

Conversation

@PureWeen

Copy link
Copy Markdown
Member

Summary

  • Prefer precise names, named methods or variables, and single-purpose responsibilities before adding implementation comments.
  • Reserve comments for durable reasons that cannot be expressed through structure alone.
  • Keep public XML documentation focused on consumer-observable behavior instead of internal implementation details.

This follows the guidance discussed in #68114 (comment) and #68114 (comment).

Validation

Documentation-only change; git diff --check passes.

Copilot AI added 2 commits August 11, 2026 09:21
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0fb5ea3b-44bb-495b-99c5-93e753ca9ce1
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0fb5ea3b-44bb-495b-99c5-93e753ca9ce1
Copilot AI lite review requested due to automatic review settings August 11, 2026 14:42
@PureWeen
PureWeen requested a review from a team as a code owner August 11, 2026 14:42

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates the Components area contributor guidance to emphasize code clarity through structure (names, extracted methods, single-responsibility units) before adding implementation comments, and to keep public XML docs focused on consumer-observable behavior rather than internal mechanics.

Changes:

  • Adds a new “Code clarity and durable knowledge” section encouraging structural clarity over narrative comments.
  • Specifies when implementation comments are appropriate (durable, non-local reasons such as cross-boundary ordering or compatibility constraints).
  • Clarifies that public XML documentation should avoid internal control-flow/lifecycle details and instead describe observable behavior.
Show a summary per file
File Description
src/Components/AGENTS.md Adds durable guidance on preferring structural clarity over comments and constrains public XML docs to consumer-facing behavior.

Review details

Tip

Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

  • Files reviewed: 1/1 changed files
  • Comments generated: 0
  • Review effort level: Lite

@PureWeen
PureWeen merged commit 4e5ba32 into dotnet:main Aug 11, 2026
16 checks passed
@dotnet-milestone-bot dotnet-milestone-bot Bot added this to the 11.0-rc1 milestone Aug 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants