C# Code Generation & Review Skill

Generate and review idiomatic, production-ready C# code that strictly follows Microsoft's .NET naming conventions, Framework Design Guidelines, and general software engineering principles.

Core Principles

Code Quality

• KISS – Prefer the simplest solution that correctly solves the problem
• YAGNI – Do not add abstractions or features not requested
• SOLID – Apply where it adds genuine value; avoid over-engineering
• DRY – Eliminate duplication, but don't abstract prematurely
• Readability first – Code is read far more than it's written

Balance

Maintainability and performance must be balanced. Optimize only when there is a measurable need. Premature optimization is the root of unnecessary complexity.

Naming Conventions

Always follow these rules — they are non-negotiable:

Rules:

• No Hungarian notation, no underscores in non-field names
• No abbreviations unless universally accepted (e.g., Id, Url, Http)
• No language-specific type names in public APIs (use GetLength, not GetInt)
• Attribute types must end with Attribute
• Async methods must end with Async

Code Structure Rules

Formatting (dotnet format compliant)

All generated code must be compatible with dotnet format out of the box. Do NOT deviate from these:

• 4-space indentation (no tabs)
• Opening braces { on the same line for expressions; new line for type and method declarations
• One blank line between methods
• using directives at the top, outside namespace
• File-scoped namespaces (namespace Foo;) for single-type files
• var for obvious types; explicit types when the type is not immediately clear

Nullability

• Enable nullable reference types (<Nullable>enable</Nullable>)
• Use ? for nullable reference types and value types where needed
• Use ArgumentNullException.ThrowIfNull() for null guards in public APIs

Modern C# Features

Use modern language features when they improve clarity:

• Records for immutable data transfer objects
• Pattern matching over type-checking casts
• is not null / is null over != null / == null
• switch expressions over verbose switch statements
• Primary constructors for simple DI scenarios
• Span<T> / Memory<T> for performance-sensitive buffer operations (only when justified)

API Design Guidelines (from Microsoft Framework Design Guidelines)

Members

• Methods must be verbs or verb phrases: CreateWorktree, ParseBranchName
• Properties must be nouns or adjectives: BranchName, IsValid
• Boolean properties use affirmative phrasing: CanSeek, IsEnabled, HasValue
• Do NOT have a property and a method with the same name (e.g., TextWriter property and GetTextWriter method is wrong)
• Collection properties use plural names describing items: Worktrees, not WorktreeList

Exceptions

• Use exceptions for execution failures, not control flow
• Do NOT return error codes; throw exceptions
• Do NOT throw NullReferenceException, IndexOutOfRangeException, AccessViolationException from public APIs
• Use Try-Parse Pattern for performance-sensitive parsing: bool TryParse(string input, out T result)
• Use Tester-Doer Pattern when checking preconditions avoids expensive throws
• Document all exceptions thrown by public members with <exception> XML doc tags
• See references/exceptions.md for detailed guidance

Parameters

• Avoid out or ref parameters in public APIs (prefer return values or records)
• Use CancellationToken as the last parameter in async methods (optional, with default)
• Validate all public API arguments and throw ArgumentException, ArgumentNullException, or ArgumentOutOfRangeException

Workflow Selection

Choose the appropriate workflow based on the request:

• Generating new code → follow Code Generation Workflow
• Reviewing existing code → follow Code Review Workflow

Code Generation Workflow

Step 1: Understand the request

Before writing code:

1. Identify what type of component is needed (class, interface, CLI command, service, controller, entity, repository, test, etc.)
2. Identify dependencies and the target framework (check .csproj if provided)
3. Check whether tests are needed (always offer to generate tests)

Step 2: Select the right references

Load reference files based on the component type:

• General naming and structure → this file is sufficient
• Exceptions and error handling → references/exceptions.md
• Async and Task-based patterns → references/async.md
• Unit testing (xUnit + Moq + Shouldly) → references/testing.md
• System.CommandLine CLI commands → references/cli.md
• System.IO.Abstractions (file system abstraction) → references/filesystem.md
• ASP.NET Core Web API (controllers, routing, DI, error handling) → references/aspnetcore.md
• Entity Framework Core (DbContext, entities, queries, migrations) → references/efcore.md

Step 3: Write the code

Follow the checklist:

Before writing:

• Plan the public API surface before writing implementation
• Identify which interfaces the type should implement
• Identify which exceptions should be thrown

While writing:

• All public members have XML documentation (///)
• Nullable reference types enabled and correct
• All public arguments validated
• Async methods suffixed with Async and accept CancellationToken
• No logic in constructors beyond assignment
• Static methods for stateless utilities
• private as the default access modifier; widen only when needed

After writing:

• Verify format matches dotnet format output (4-space indent, correct brace placement)
• Confirm no abbreviations in public API names
• Confirm no Hungarian notation
• Confirm no error codes returned

Step 4: Output format

Always present code as complete, compilable files. Include:

1. The complete file with using directives and namespace
2. A brief explanation of design decisions
3. Example usage (inline comment or separate snippet)
4. Offer to generate unit tests if not already requested

Code Review Workflow

Step 1: Understand scope

1. Read all provided files before commenting
2. Identify which stack is in use: CLI / ASP.NET Core / EF Core / plain class library
3. Load the relevant reference files for that stack (same list as above)

Step 2: Review against all applicable rules

Check every file for:

Naming & formatting

• All naming conventions followed (see table above)
• No Hungarian notation, no abbreviations in public names
• No tabs; 4-space indent; file-scoped namespaces used
• Async methods suffixed with Async

API design

• Methods are verbs; properties are nouns/adjectives
• No error codes returned — exceptions used instead
• No NullReferenceException / IndexOutOfRangeException from public APIs
• CancellationToken accepted where appropriate

Nullability & safety

• Nullable reference types enabled and correctly annotated
• All public API arguments validated before use

Stack-specific (load relevant reference and apply its checklist)

• ASP.NET Core: controller shape, routing, DI lifetimes, response types, error handling
• EF Core: no N+1, AsNoTracking on reads, async EF methods, no raw SQL injection

Tests

• Tests exist for public behaviour
• AAA structure followed; Shouldly used; no raw Assert.

Step 3: Report findings

Structure feedback by severity:

🔴 CRITICAL — Must fix: bugs, security issues, data corruption risk, lifetime mismatches
🟠 HIGH — Should fix before merge: naming violations, missing argument validation, anti-patterns
🟡 MEDIUM — Improvements: test coverage gaps, missing XML docs, suboptimal queries
🟢 LOW — Optional polish: style, refactoring opportunities
✅ POSITIVE — What is done well (always include at least one)

For each issue provide:

1. The problematic code snippet
2. Why it is a problem
3. A corrected example
4. Reference to the specific guideline broken

Examples

✅ Correct: Service class with DI, nullability, and documentation

using System.IO.Abstractions;

namespace Kuju63.WorkTree;

/// <summary>
/// Manages git worktree lifecycle operations.
/// </summary>
public sealed class WorktreeManager(IFileSystem fileSystem, IGitRunner gitRunner)
{
    private readonly IFileSystem _fileSystem = fileSystem ?? throw new ArgumentNullException(nameof(fileSystem));
    private readonly IGitRunner _gitRunner = gitRunner ?? throw new ArgumentNullException(nameof(gitRunner));

    /// <summary>
    /// Creates a new worktree at the specified path for the given branch.
    /// </summary>
    /// <param name="path">The directory path for the new worktree.</param>
    /// <param name="branchName">The branch name to check out in the worktree.</param>
    /// <param name="cancellationToken">A token to observe for cancellation requests.</param>
    /// <exception cref="ArgumentNullException">
    /// Thrown when <paramref name="path"/> or <paramref name="branchName"/> is null.
    /// </exception>
    /// <exception cref="WorktreeException">Thrown when git fails to create the worktree.</exception>
    public async Task CreateAsync(string path, string branchName, CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(path);
        ArgumentNullException.ThrowIfNull(branchName);

        await _gitRunner.RunAsync(["worktree", "add", path, branchName], cancellationToken);
    }
}

✅ Correct: Record for data transfer

namespace Kuju63.WorkTree;

/// <summary>
/// Represents an existing git worktree entry.
/// </summary>
public record WorktreeInfo(string Path, string BranchName, bool IsLocked);

✅ Correct: Try-Parse pattern

/// <summary>Parses a branch name from raw git output.</summary>
public static bool TryParseBranchName(string input, out string branchName)
{
    branchName = string.Empty;
    if (string.IsNullOrWhiteSpace(input))
        return false;

    var trimmed = input.Trim();
    if (!trimmed.StartsWith("refs/heads/", StringComparison.Ordinal))
        return false;

    branchName = trimmed["refs/heads/".Length..];
    return true;
}

❌ Wrong: Naming and style violations

// BAD: Hungarian notation, abbreviation, missing nullable, no docs
class wtMgr {
  private IFileSystem fs; // 'fs' abbreviation, missing _prefix, no ?
  public string getBranchNm() => ""; // lowercase method, abbreviation
}

Quick Reference