Skip to content

Conversation

oii-nasif
Copy link
Contributor

Summary

  • Updated Enumerable.Prepend<TSource> summary to clarify it returns a new sequence
  • Changed from "Adds a value" (implies modification) to "Returns a new sequence" (accurate behavior)

Details

The Enumerable.Prepend<TSource> method had a confusing summary that stated "Adds a value to the beginning of the
sequence." This wording incorrectly implied that the method modifies the original sequence in place.

The Problem

The original summary was misleading because:

  • "Adds a value" suggests in-place modification
  • Developers might expect the source sequence to be changed
  • This contradicts LINQ's core principle of deferred execution and immutability

While the Remarks section included a note clarifying "This method does not modify the elements of the collection.
Instead, it creates a copy of the collection with the new element," the summary itself was still confusing and
contradictory.

Changes Made

Updated the summary from:

Adds a value to the beginning of the sequence.

To:

Returns a new sequence that begins with the specified element followed by the elements of the source sequence.

Why This Matters

This clarification helps developers:

  • Understand that Prepend follows LINQ's immutability pattern
  • Avoid expecting the source collection to be modified
  • Write correct code that properly handles the returned sequence
  • Align with how other LINQ methods like Append, Select, Where, etc. are documented

The new wording is consistent with the Returns section which already correctly stated "A new sequence that begins
with element."

Fixes #11745

Changed the summary from "Adds a value to the beginning of the
  sequence" to "Returns a new sequence that begins with the specified
  element followed by the elements of the source sequence."

  The previous wording incorrectly implied in-place modification of
  the original sequence. The new wording makes it clear that Prepend
  returns a new sequence without modifying the source, consistent with
  LINQ's deferred execution and immutability principles.
@oii-nasif oii-nasif requested a review from a team as a code owner October 4, 2025 22:15
@github-actions github-actions bot added the needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners label Oct 4, 2025
@dotnet-policy-service dotnet-policy-service bot added the community-contribution Indicates that the PR has been added by a community member label Oct 4, 2025
@BillWagner BillWagner closed this Oct 6, 2025
@BillWagner BillWagner reopened this Oct 6, 2025
@BillWagner BillWagner added area-System.Linq and removed needs-area-label An area label is needed to ensure this gets routed to the appropriate area owners labels Oct 6, 2025
Copy link
Contributor

Tagging subscribers to this area: @dotnet/area-system-linq

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-System.Linq community-contribution Indicates that the PR has been added by a community member
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Confusing Function Definition for Enumerable.Prepend<TSource>(IEnumerable<TSource>, TSource) Method
2 participants