Development Guide

This guide covers coding standards, testing conventions, and the contribution workflow for the TestClone project.

Coding Standards

Language and Framework Versions

• C# 14 — use the latest language features (primary constructors, pattern matching, collection expressions, etc.).
• .NET 10 / ASP.NET Core 10 — target net10.0 for all projects.

Naming Conventions

Construct	Convention	Example
Types, methods, public members	PascalCase	CreateOrder, OrderId
Interfaces	I prefix + PascalCase	IFacade
Private fields	_camelCase	_facade
Local variables, parameters	camelCase	createOrderRequest

Formatting

• File-scoped namespace declarations and single-line using directives.
• Insert a blank line before every opening { of a control-flow block (if, for, foreach, using, try, etc.).
• Final return statement on its own line.
• Prefer pattern matching and switch expressions over if/else chains.
• Use nameof(...) instead of string literals when referring to member names.
• Apply formatting rules from .editorconfig — the CI pipeline enforces these.

Null Safety

• All projects have Nullable enabled; declare variables as non-nullable unless intentionally nullable.
• Check for null at public entry points.
• Use is null / is not null — never == null / != null.

XML Documentation

Every public API surface (classes, interfaces, methods, properties) must have an XML <summary> comment. Include <param>, <returns>, and optionally <example> / <code> where appropriate.

/// <summary>
/// Creates a new product order based on the provided request.
/// </summary>
/// <param name="request">The order creation request containing product name and quantity.</param>
/// <returns>A task that returns the created order response with order ID and status.</returns>
Task<CreateOrderResponse> CreateOrder(CreateOrderRequest request);

Code Quality

• Warnings treated as errors (Directory.Build.props): all compiler warnings must be resolved before merging.
• Prefer constructor injection for all dependencies; register services in Program.cs.
• Keep controllers thin — delegate all business logic to IFacade.

Testing

Frameworks

Library	Purpose
TUnit	Unit testing framework
Moq	Mocking / test-double creation

Test Project Layout

Project	What it tests
src/WebApi.UnitTests	Controllers (mocked IFacade)
src/DomainApi.UnitTests	Facade business logic (no mocking needed)

Test Naming Convention

ClassNameMethodNameExpectedBehavior

Example: TestCloneControllerGetTestOperationReturnsOkWithFacadeResult

Test Structure

Use // Arrange, // Act, // Assert comments to clearly separate the three phases:

[Test]
public async Task TestCloneControllerGetTestOperationReturnsOkWithFacadeResult()
{
    // Arrange
    var mockFacade = new Mock<IFacade>();
    mockFacade.Setup(f => f.TestOperation()).ReturnsAsync("Hello from the Facade!");
    var controller = new TestCloneController(mockFacade.Object);

    // Act
    var result = await controller.GetTestOperation();

    // Assert
    var okResult = result as OkObjectResult;
    await Assert.That(okResult).IsNotNull();
    await Assert.That(okResult!.Value).IsEqualTo("Hello from the Facade!");
}

Conventions

• Do not use _ in test method names.
• Do not use FluentAssertions — use TUnit's built-in Assert.That(...) assertions.
• Do not add XML documentation comments to test methods.
• Always cover the critical paths of every new feature.

Running Tests

# All tests
dotnet test

# Single test project
dotnet test src/WebApi.UnitTests
dotnet test src/DomainApi.UnitTests

Adding a New Endpoint

1. DomainModel — Add request/response DTOs in src/DomainModel/Requests/ and src/DomainModel/Responses/.
2. DomainApi — Add the operation signature to IFacade and implement it in Facade.
3. WebApi — Add a new action method to TestCloneController (or a new controller if the domain warrants it).
4. Tests — Add unit tests for both the controller action (mock IFacade) and the Facade implementation.

Contribution Workflow

1. Fork or branch from main.
2. Implement your changes following the coding standards above.
3. Ensure dotnet build produces zero warnings.
4. Ensure dotnet test passes with all tests green.
5. Open a Pull Request using the provided PR template (.github/pull_request_template.md).
6. Address review feedback and update your branch as needed.

Useful Commands

# Build (warnings treated as errors)
dotnet build

# Run the API locally
dotnet run --project src/WebApi

# Run all unit tests
dotnet test

# Restore NuGet packages
dotnet restore

Related Documentation

• Home — project overview and navigation.
• Getting Started — first-time setup.
• API Reference — available endpoints.
• Architecture Overview — layer responsibilities and design patterns.