csharp-coding

C# Coding Standards

Naming Conventions

Element	Convention	Example
Namespace	PascalCase, match folder	YourOrg.Payments.Domain
Class/Record	PascalCase	OrderService, PaymentRequest
Interface	IPascalCase	IOrderRepository
Method	PascalCase	GetOrderByIdAsync
Property	PascalCase	TotalAmount
Parameter/Local	camelCase	orderId, paymentResult
Private field	_camelCase	_orderRepository
Constant	PascalCase	MaxRetryCount
Async method	Suffix with Async	ProcessPaymentAsync

Async/Await

• Always use async/await for I/O-bound operations — never .Result or .Wait()
• Return Task<T> or ValueTask<T> from async methods
• Use ConfigureAwait(false) in library code, omit in application code
• Prefer ValueTask<T> for hot paths that often complete synchronously
• Use CancellationToken parameters on all async public APIs

// Good
public async Task<Order> GetOrderAsync(int id, CancellationToken ct = default)
{
    return await _repository.FindByIdAsync(id, ct);
}

// Bad — blocks thread
public Order GetOrder(int id)
{
    return _repository.FindByIdAsync(id).Result;
}

Nullable Reference Types

• Enable <Nullable>enable</Nullable> in all projects
• Use ? for nullable references: string? name
• Use null-conditional: order?.Customer?.Name
• Use null-coalescing: name ?? "Unknown"
• Never suppress warnings with ! unless absolutely necessary (document why)

Pattern Matching

• Use is patterns for type checks: if (result is SuccessResult success)
• Use switch expressions for multi-branch logic
• Prefer pattern matching over as + null check

var message = result switch
{
    SuccessResult s => $"Order {s.OrderId} created",
    ValidationError e => $"Validation failed: {e.Message}",
    NotFoundError => "Order not found",
    _ => "Unknown error"
};

LINQ

• Prefer method syntax over query syntax for simple operations
• Use query syntax for complex joins
• Never use LINQ in hot paths — prefer for loops
• Always materialize before returning: .ToList(), .ToArray()

Error Handling

• Use Result<T> pattern in application layer — never throw for expected failures
• Throw only for truly exceptional conditions (programmer error, infrastructure failure)
• Always catch specific exceptions, never bare catch (Exception)
• Use ExceptionFilter middleware for unhandled exceptions in ASP.NET Core
• Log context with exceptions: _logger.LogError(ex, "Failed to process order {OrderId}", orderId)

Dependency Injection

• Register services in Program.cs or dedicated ServiceCollectionExtensions
• Use constructor injection — never ServiceLocator pattern
• Prefer IOptions<T> for configuration
• Register transient for stateless services, scoped for per-request, singleton only when truly shared
• Max 5 constructor dependencies — if more, the class does too much

Records and Immutability

• Use record for DTOs, value objects, and request/response types
• Use init properties for immutable objects
• Prefer immutable collections (IReadOnlyList<T>) in public APIs