
## Introduction

Even well-written methods become hard to maintain when files and projects are organized inconsistently.

This post covers practical structure rules for teams.

## 1) Organize class members consistently

A common order:

1. constants / static readonly fields
2. private fields
3. constructors
4. public properties
5. public methods
6. private methods

Consistency reduces navigation time and review friction.

## 2) Keep related logic close together

Private helper methods should appear near the public method that uses them.

Avoid scattering related logic across long files.

## 3) One class per file (most of the time)

Use file names that match class names.

- `OrderService.cs` -> `OrderService`
- `OrderNotFoundException.cs` -> `OrderNotFoundException`

Exception: tiny related types such as a request record near a small service.

## 4) Avoid overusing regions

If a class requires many `#region` blocks to be readable, the class is likely too large.

Refactor by extracting smaller cohesive classes.

## 5) Keep project boundaries clear

A clean architecture baseline:

- Domain: entities, value objects, domain rules
- Application: use cases, DTOs, interfaces, validators
- Infrastructure: databases, external APIs, file storage
- WebApi: controllers, middleware, composition root

This separation makes ownership and dependencies explicit.

## 6) Comments: explain why, not what

### Bad comment

```csharp
// Check if user is admin
if (user.Role == Role.Admin)
{
    // ...
}
```

### Better code and better comment style

```csharp
if (user.IsAdmin)
{
    // Discount capped at 30% due to compliance policy REG-2024-117
    discount = Math.Min(discount, 0.30m);
}
```

Comment only when context or business rule is not obvious.

## 7) Document public APIs with XML comments

```csharp
/// <summary>
/// Retrieves an order by its unique identifier.
/// </summary>
/// <param name="id">The order ID.</param>
/// <param name="ct">Cancellation token.</param>
/// <returns>The order, or null if not found.</returns>
public Task<Order?> GetByIdAsync(int id, CancellationToken ct);
```

## 8) Delete commented-out code

Version control already preserves history. Dead commented blocks make files noisy and misleading.

## Summary

Code organization and documentation are force multipliers. Clear structure plus intentional comments makes large C# codebases easier to evolve safely.


Organize C# projects and classes for maintainability, and write comments that explain why instead of what.

C# Code Organization and Documentation Without Noise — Clean Code


## Introduction

Clean methods help locally; clean class design helps globally.

When classes are too large or tightly coupled, every change becomes risky. This post shows practical class design rules based on SOLID.

## 1) Single Responsibility Principle (SRP)

A class should have one reason to change.

### Bad: one class does everything

```csharp
public class OrderService
{
    public void PlaceOrder(Order order)
    {
        Validate(order);
        Save(order);
        SendNotification(order);
    }
}
```

### Better: split by responsibility

```csharp
public class OrderValidator
{
    public void Validate(Order order) { /* ... */ }
}

public class OrderRepository
{
    public Task SaveAsync(Order order, CancellationToken ct) => Task.CompletedTask;
}

public class OrderNotifier
{
    public Task NotifyAsync(Order order, CancellationToken ct) => Task.CompletedTask;
}

public class OrderService(
    OrderValidator validator,
    OrderRepository repository,
    OrderNotifier notifier)
{
    public async Task PlaceOrderAsync(Order order, CancellationToken ct)
    {
        validator.Validate(order);
        await repository.SaveAsync(order, ct);
        await notifier.NotifyAsync(order, ct);
    }
}
```

## 2) Depend on abstractions, not concretions

High-level classes should not instantiate low-level dependencies directly.

```csharp
// BAD
public class SqlReportRepository
{
    public async Task<ReportData> GetDataAsync(int id, CancellationToken ct)
    {
        return new ReportData("Monthly Sales");
    }
}

public class ReportGenerator
{
    private readonly SqlReportRepository _repository;

    public ReportGenerator()
    {
        _repository = new SqlReportRepository();
    }

    public async Task<Report> GenerateAsync(int id, CancellationToken ct)
    {
        var data = await _repository.GetDataAsync(id, ct);
        return BuildReport(data);
    }

    private static Report BuildReport(ReportData data) => new(data.Title);
}

// GOOD
public interface IReportRepository
{
    Task<ReportData> GetDataAsync(int id, CancellationToken ct);
}

public class ReportGenerator(IReportRepository repository)
{
    public async Task<Report> GenerateAsync(int id, CancellationToken ct)
    {
        var data = await repository.GetDataAsync(id, ct);
        return BuildReport(data);
    }

    private static Report BuildReport(ReportData data) => new(data.Title);
}
```

This makes the class easier to test and swap implementations.

## 3) Prefer composition over inheritance

Inheritance can create brittle hierarchies.

```csharp
// BAD
public class FlyMovement
{
    public void Move() => Console.WriteLine("Flying");
}

public class WalkMovement
{
    public void Move() => Console.WriteLine("Walking");
}

public class Animal
{
    private readonly FlyMovement _flyMovement;
    private readonly WalkMovement _walkMovement;
    private readonly string _type;

    public Animal(string type)
    {
        _type = type;
        _flyMovement = new FlyMovement();
        _walkMovement = new WalkMovement();
    }

    public void Move()
    {
        if (_type == "Bird")
        {
            _flyMovement.Move();
        }
        else if (_type == "Dog")
        {
            _walkMovement.Move();
        }
    }
}


// GOOD
public interface IMovementStrategy
{
    void Move();
}

public class FlyMovement : IMovementStrategy
{
    public void Move() => Console.WriteLine("Flying");
}

public class WalkMovement : IMovementStrategy
{
    public void Move() => Console.WriteLine("Walking");
}

public class Animal(IMovementStrategy movement)
{
    public void Move() => movement.Move();
}
```

You can change behavior by changing strategy, not by rewriting class trees.

## 4) Keep classes cohesive

A cohesive class has members that all support one purpose.

Warning signs:

- class has multiple groups of unrelated fields
- methods only use a small subset of fields
- class keeps growing with `#region` blocks

When these appear, extract classes.

## 5) Open/Closed principle in practice

Avoid repeated `if/switch` chains that must be edited for each new type.

```csharp
public abstract class Shape
{
    public abstract double CalculateArea();
}

public class Circle(double radius) : Shape
{
    public override double CalculateArea() => Math.PI * radius * radius;
}

public class Rectangle(double width, double height) : Shape
{
    public override double CalculateArea() => width * height;
}
```

New behavior is added by extension, not by changing old code.

## Summary

Strong class design reduces coupling and change risk. Start with SRP and dependency inversion; these two practices usually deliver immediate maintainability gains.


Learn how to apply SRP, dependency inversion, and composition in C# to build maintainable, extensible production services.

Architecture

C# Code Organization and Documentation Without Noise — Clean Code

C# Class Design and SOLID Principles in Real Projects — Clean Code