swe-programming-csharp

name	swe-programming-csharp
description	C# coding standards from authoritative docs/explanation/software-engineering/programming-languages/c-sharp/ documentation

C# Coding Standards

Purpose

Progressive disclosure of C# coding standards for agents writing C# code.

Usage: Auto-loaded for agents when writing C# code. Provides quick reference to idioms, best practices, and antipatterns.

Authoritative Source: docs/explanation/software-engineering/programming-languages/c-sharp/README.md

Prerequisite Knowledge

IMPORTANT: This skill provides OSE Platform-specific style guides, not educational tutorials.

Complete the AyoKoding C# learning path first:

1. C# Learning Path - 0-95% language coverage
2. C# By Example - 75+ annotated examples

See: Programming Language Documentation Separation

Quick Standards Reference

Naming Conventions

Classes/Interfaces/Methods/Properties: PascalCase

• ZakatCalculator, IZakatRepository, CalculateAmount(), TotalWealth

Local Variables/Parameters: camelCase

• zakatAmount, nisabThreshold, paymentDate

Private Fields: _camelCase prefix

• private readonly IZakatRepository _repository;

Constants: PascalCase

• public const decimal ZakatRate = 0.025m;

Nullable Reference Types

// CORRECT: Enable nullable in .csproj
// <Nullable>enable</Nullable>

// CORRECT: Non-nullable by default
public string ContractId { get; init; } = string.Empty;

// CORRECT: Nullable when intentional
public string? Notes { get; init; }

// CORRECT: Null-forgiving with justification
var value = GetValue()!; // Safe because we validated above

Records for Value Objects

// CORRECT: Record for immutable value object
public record ZakatCalculation(
    decimal Wealth,
    decimal Nisab,
    decimal Amount,
    DateOnly CalculationDate
)
{
    public static ZakatCalculation Calculate(decimal wealth, decimal nisab)
    {
        var amount = wealth >= nisab ? wealth * 0.025m : 0m;
        return new ZakatCalculation(wealth, nisab, amount, DateOnly.FromDateTime(DateTime.UtcNow));
    }
}

Async/Await

// CORRECT: async Task with CancellationToken
public async Task<ZakatCalculation> CalculateAsync(
    decimal wealth,
    CancellationToken cancellationToken = default)
{
    var nisab = await _repository.GetCurrentNisabAsync(cancellationToken);
    return ZakatCalculation.Calculate(wealth, nisab);
}

// WRONG: Blocking async code
public ZakatCalculation Calculate(decimal wealth)
{
    var nisab = _repository.GetCurrentNisabAsync().Result; // DEADLOCK RISK!
    return ZakatCalculation.Calculate(wealth, nisab);
}

Error Handling

// CORRECT: ProblemDetails for HTTP errors (RFC 7807)
app.UseExceptionHandler(exceptionHandlerApp =>
    exceptionHandlerApp.Run(async context =>
    {
        context.Response.ContentType = "application/problem+json";
        var problemDetails = new ProblemDetails
        {
            Status = StatusCodes.Status500InternalServerError,
            Title = "An unexpected error occurred"
        };
        await context.Response.WriteAsJsonAsync(problemDetails);
    }));

// CORRECT: Result pattern for domain errors
public Result<ZakatCalculation> Calculate(decimal wealth, decimal nisab)
{
    if (wealth < 0)
        return Result.Failure<ZakatCalculation>("Wealth cannot be negative");

    return Result.Success(ZakatCalculation.Calculate(wealth, nisab));
}

Testing with xUnit and FluentAssertions

public class ZakatCalculatorTests
{
    [Theory]
    [InlineData(10000, 5000, 250)]
    [InlineData(3000, 5000, 0)]
    public async Task CalculateAsync_ReturnsCorrectAmount(
        decimal wealth, decimal nisab, decimal expectedAmount)
    {
        // Arrange
        var mockRepo = new Mock<IZakatRepository>();
        mockRepo.Setup(r => r.GetCurrentNisabAsync(It.IsAny<CancellationToken>()))
                .ReturnsAsync(nisab);
        var calculator = new ZakatCalculator(mockRepo.Object);

        // Act
        var result = await calculator.CalculateAsync(wealth);

        // Assert
        result.Amount.Should().Be(expectedAmount);
    }
}

Comprehensive Documentation

Authoritative Index: docs/explanation/software-engineering/programming-languages/c-sharp/README.md

Mandatory Standards

1. Coding Standards
2. Testing Standards
3. Code Quality Standards
4. Build Configuration

Context-Specific Standards

1. Error Handling
2. Concurrency
3. Type Safety
4. Performance
5. Security
6. API Standards
7. DDD Standards
8. Framework Integration

Related Skills

• docs-applying-content-quality
• repo-practicing-trunk-based-development

References

• C# README
• Functional Programming