C# Coding Standards & Best Practices

C# Coding Standards & Best Practices

This skill outlines the mandatory coding standards and best practices for all C# development in the Guitar Alchemist repository. Adherence to these guidelines ensures codebase consistency, readability, and leverage of modern language features.

1. Modern C# Features (C# 12+)

We explicitly encourage the latest C# features where they improve clarity and conciseness.

1.1 Records & Immutability

• Prefer record for Data Transfer Objects (DTOs), Domain Events, and Value Objects.
• Use primary constructors for concise initialization.
• Immutability by default: Use init accessors instead of set unless mutation is strictly required.

// DO:
public record ChordVoicing(string Name, int[] Frets, PitchClass Root);

// DON'T:
public class ChordVoicing
{
    public string Name { get; set; }
    // ...
}

1.2 Pattern Matching

• Use pattern matching (is, switch expressions) over if-else chains and type casting.
• Leverage list patterns and property patterns for expressive logic.

var description = voicing switch
{
    { Frets: [0, ..] } => "Open Chord",
    { Difficulty: > 0.8 } => "Advanced Voicing",
    _ => "Standard Voicing"
};

1.3 Collection Expressions

• Use collection expressions ([]) for initialization.
• IDE0300/IDE0301/IDE0305: Always fix these warnings by converting to collection expressions.

// DO:
int[] notes = [0, 4, 7];
List<string> scale = ["C", "D", "E"];
var copy = new List<int>([..original]);

// DON'T:
int[] notes = new int[] { 0, 4, 7 };
var list = new List<string> { "A", "B" }; // IDE0300 Warning

2. Architecture & Organization

2.1 Namespace Structure

Follow the standard structure: GA.<Layer>.<Module>.<Component>

• Common: Shared logic, primitives, and utilities.
• Domain: Pure business logic, entities, and aggregates.
• Business: Application logic, services, and workflows.
• Infrastructure: External concerns (Database, GPU, Filesystem).