Csharp Style

C# Style

Hold the code to an enterprise production standard, never the level of tutorial or learning material. Write in a strict, technical style: no explanatory scaffolding, no didactic comments.

Naming and layout

• Give every identifier its full domain meaning; never use a single-character or abbreviated name.
• Suffix a method returning Task or Task<T> with Async.
• Follow .editorconfig rules

Language features

• Use the var keyword to declare variables.
• Use the newest language features, patterns, types.
• Use nameof instead of a string literal for a member or parameter name.
• Use raw string literals (""") for multi-line or quote-heavy text, and interpolation elsewhere.
• Use primary constructors to capture dependencies and simple state.
• Use required members instead of a constructor whose only job is to force initialization.
• Use range and index operators (^, ..) for slicing.
• Use is null or is not null for null checks; never the empty property pattern is { } as a null check.
• Use separate if blocks for if-return conditions; don't list all the conditions within a single if block.
• Use pattern matching, collection expressions, switch expressions.
• Use declaration pattern to check the run-time type of an expression and, if a match succeeds, assign an expression result to a declared variable.
• Use type pattern to check the run-time type of an expression.
• Use constant pattern to test that an expression result equals a specified constant.
• Use relational patterns to compare an expression result with a specified constant.
• Use logical patterns to test that an expression matches a logical combination of patterns.
• Use property pattern to test that an expression's properties or fields match nested patterns.
• Use positional pattern to deconstruct an expression result and test if the resulting values match nested patterns.
• Use var pattern to match any expression and assign its result to a declared variable.
• Use discard pattern to match any expression.
• Use list patterns to test that a sequence of elements matches corresponding nested patterns.
• Use source generators from System and external libraries; ObservableProperty, LoggerMessage, JsonSerializerContext and others.
• Use the System.Memory features and types, if this doesn't reduce code readability.
• Use Polyfill when the project targets multiple frameworks; it brings new types and methods to legacy targets without copying .NET sources.

Nullability

• Use nullable types; keep public and internal contracts null-safe.
• Use = null! suppression only where the value is never null.

Annotations

• Express contracts with annotations from the JetBrains and System.Diagnostics.CodeAnalysis sets — both are large; reach for whichever fits, not a fixed few.
• Use [Pure] if the method doesn't make any observable state changes.
• Use [NotNullWhen] on Try-style methods with an out nullable result.
• Use [PublicAPI] to mark a publicly available API or DTO that must not be removed. The annotation keeps the symbol out of the unused-symbol report.
• Use [UsedImplicitly] to mark a symbol as used implicitly.
• Use [MustUseReturnValue], [MemberNotNull], [DoesNotReturnIf], [StringSyntax] and others if applicable.

Asynchronous code

• Use Task/Task<T>; reserve async void for a framework-required event handler.
• Flow CancellationToken through I/O, broker, storage, and long-running work.
• Never block an async flow with .Result, .Wait(), or synchronous sleeps.

Data contracts

• Use record for DTOs, message contracts, and configuration-style data.
• Use init properties if applicable.

Error handling

• Guard a public method's arguments at entry; throw ArgumentNullException, ArgumentException, or ArgumentOutOfRangeException.
• Throw the most specific exception type; never throw Exception, SystemException, or ApplicationException directly.
• Rethrow with throw;; never throw exception;.

Extensions methods and properties

• An extension method is declared inside an extension block, never with a this parameter.
• A registration extension is named for its net effect on the container: Add* when something resolves after the call that did not before, Configure* when the call only supplies settings. Split a registration by phase, never by verb.
• The file suffix of an extension class follows the host phase, never the verb of the method inside. *Registration.cs holds everything that runs before Build(), whether the method reads Add* or Configure*. *Endpoints.cs holds everything that runs after it, the Map* calls on WebApplication and IEndpointRouteBuilder. A class that carries both phases is split into two files.
• *Configuration.cs names a type that configures something — an IConfigureOptions<T> or an equivalent configurator — and never an extension class. *Extensions.cs names ordinary extension methods over a domain or framework type, and an Aspire resource decorator returning IResourceBuilder<T> keeps the With* verb.

Performance

• Do not use deep optimization if it affects code readability.
• Use Span if it avoids allocations without significant code changes.
• Use struct for internal value types on a hot path; keep them inside the owning type and don't expose them across a public boundary. A value type allocates nothing.
• Dispose owned streams and pooled resources.
• Unsubscribe from events depending on the object lifetime.
• Use source-generated types in place of their reflection-based equivalents. A generated type carries no extra allocation and no reflection overhead.

Comments

• Comment the intent, constraint, or invariant the code cannot show; add none when the code already states it.
• Judge every comment as final standalone text: the reader has only the code as it stands, with no previous version, diff, or request to compare against; drop any comment that merely narrates the change.
• State facts in the present indicative; never argue why the code is as it is.
• Cut every purpose, result, cause, or comparison clause (so, that makes, which makes, because, rather than); if the clause states a fact the reader needs, make it its own sentence.

Review

• Identifiers carry full domain meaning; async methods end in Async.
• Modern language features are used: var, pattern matching, collection and switch expressions, and source generators over hand-written equivalents.
• Nullability is explicit and annotations match real contracts.
• Async paths flow CancellationToken and never block.
• Shared data contracts are immutable record types; a DTO carries [PublicAPI].
• Exceptions are specific types, arguments are guarded at entry, and rethrows use throw;.
• Hot paths avoid needless allocations (struct, Span); owned disposables and event subscriptions are released on the owner's lifetime.
• Comments state facts about the code as it stands; none narrates the edit or argues why.