Skip to content

Add warnings and guidance against using volatile keyword #47282

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.

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
merged 3 commits into from
Jul 15, 2025

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Jul 10, 2025

Fixes #23832

The volatile keyword documentation now includes prominent warnings about its limitations and strongly recommends safer alternatives for multithreaded programming.

Changes Made

  • Added prominent CAUTION block warning against misuse of volatile early in the document
  • Created new "Alternatives to volatile" section explaining safer options:
    • System.Threading.Interlocked operations for atomic operations
    • lock statements for mutual exclusion
    • System.Threading.Volatile class for explicit volatile operations
    • Higher-level synchronization primitives and concurrent collections
  • Enhanced existing content to emphasize safer alternatives throughout the document
  • Expanded "See also" section with modern threading resources

Why These Changes

The C# community has identified that volatile is often misunderstood and misused, leading to subtle concurrency bugs. The existing documentation provided technical information but lacked guidance about when not to use volatile and what to use instead.

What This Addresses

  • Warns developers about common misconceptions with volatile
  • Explains that volatile doesn't provide atomicity, prevent race conditions, or guarantee memory ordering
  • Directs developers toward modern, safer concurrency tools
  • Maintains all existing technical content for those who need to understand volatile

The documentation now follows the community consensus that volatile should be avoided in favor of more reliable alternatives while still providing the technical details for advanced scenarios.


💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.


Internal previews

📄 File 🔗 Preview link
docs/csharp/language-reference/keywords/volatile.md docs/csharp/language-reference/keywords/volatile

@BillWagner
Copy link
Member

@copilot Can you start working on this again?

@Copilot Copilot AI changed the title [WIP] Include warnings against using volatile Add warnings and guidance against using volatile keyword Jul 10, 2025
Copilot finished work on behalf of BillWagner July 10, 2025 20:38
Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

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

Great start @copilot

I've got one comment for you to address.

Copy link
Contributor Author

Copilot AI commented Jul 14, 2025

@copilot Can you start working on this again?

Addressed the review feedback by removing the "stronger guarantees" statement as requested. The documentation now focuses on these alternatives being "less prone to subtle concurrency bugs" instead. (commit: 4be8d35)

@Copilot Copilot AI requested a review from BillWagner July 14, 2025 17:55
Copilot finished work on behalf of BillWagner July 14, 2025 17:55
Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

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

This LGTM. I'll mark it ready for final review.

@BillWagner BillWagner marked this pull request as ready for review July 14, 2025 18:20
@BillWagner BillWagner requested a review from a team as a code owner July 14, 2025 18:20
@BillWagner BillWagner requested a review from IEvangelist July 14, 2025 18:20
@IEvangelist IEvangelist merged commit 1d3790d into main Jul 15, 2025
10 checks passed
@IEvangelist IEvangelist deleted the copilot/fix-23832 branch July 15, 2025 17:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dotnet-csharp/svc lang-reference/subsvc okr-quality Content-quality KR: Concerns article defects (bugs), freshness, or build warnings.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Include warnings against using volatile
3 participants