klod68/guard-clause-validation

---

name: guard-clause-validation description: "Use when writing any public method that receives parameters, adding guard clauses to existing code, or when a NullReferenceException or ArgumentException is bubbling from deep in the call stack and you need to standardize validation at the entry boundary. Covers ArgumentNullException.ThrowIfNull, ArgumentException.ThrowIfNullOrWhiteSpace, ArgumentOutOfRangeException range guards, a custom Guard static helper with CallerArgumentExpression, and Design by Contract precondition patterns. Domain: Defensive Programming, API Design. Level: Foundational. Tags: validation, guard-clauses, defensive-programming, fail-fast, argument-validation."

Guard Clause Validation

Problem

Methods receive invalid arguments and fail deep inside the call stack with cryptic errors (NullReferenceException on line 47 of an internal method). The root cause — a bad input — is obscured.

Solution: Fail Fast at the Boundary

Validate all incoming arguments at the top of public methods. Throw precise, descriptive exceptions immediately. Never let bad data travel deeper into the system.

Core Principle

Guard the gate, not the hallway. Validate at the public API boundary; internal methods can trust their inputs.

Implementation

Option A: Use built-in .NET 6+ guards

public void ProcessOrder(Order order, string customerId, int quantity)
{
    ArgumentNullException.ThrowIfNull(order);
    ArgumentException.ThrowIfNullOrWhiteSpace(customerId);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(quantity);

    // Safe to proceed — all arguments validated
    _repository.Save(order);
}

Option B: Build a Guard static helper for richer checks

/// <summary>
/// Static guard clause helper for argument validation.
/// </summary>
public static class Guard
{
    /// <summary>Throws if <paramref name="value"/> is null.</summary>
    public static T NotNull<T>(T? value, string paramName) where T : class
        => value ?? throw new ArgumentNullException(paramName);

    /// <summary>Throws if <paramref name="value"/> is null or whitespace.</summary>
    public static string NotNullOrEmpty(string? value, string paramName)
        => string.IsNullOrWhiteSpace(value)
            ? throw new ArgumentException("Value cannot be null or empty.", paramName)
            : value;

    /// <summary>Throws if <paramref name="value"/> is not within the specified range.</summary>
    public static int InRange(int value, int min, int max, string paramName)
        => value < min || value > max
            ? throw new ArgumentOutOfRangeException(paramName, value, $"Must be between {min} and {max}.")
            : value;

    /// <summary>Throws if the collection is null or empty.</summary>
    public static IReadOnlyCollection<T> NotEmpty<T>(IReadOnlyCollection<T>? collection, string paramName)
        => collection is null || collection.Count == 0
            ? throw new ArgumentException("Collection cannot be null or empty.", paramName)
            : collection;

    /// <summary>Throws if the condition is false.</summary>
    public static void Requires(bool condition, string message)
    {
        if (!condition)
            throw new ArgumentException(message);
    }
}

Usage

public IPagedResult<T> Paginate<T>(IReadOnlyCollection<T> items, int page, int pageSize)
{
    Guard.NotEmpty(items, nameof(items));
    Guard.InRange(page, 1, int.MaxValue, nameof(page));
    Guard.InRange(pageSize, 1, 500, nameof(pageSize));

    return new PagedResult<T>(items, page, pageSize);
}

Guard Clause Decision Matrix

| Check | .NET Built-in (6+) | Custom Guard | |-------|-------------------|-------------| | Null reference | ArgumentNullException.ThrowIfNull | Guard.NotNull | | Null/empty string | ArgumentException.ThrowIfNullOrWhiteSpace | Guard.NotNullOrEmpty | | Negative number | ArgumentOutOfRangeException.ThrowIfNegative | Guard.InRange | | Range check | ArgumentOutOfRangeException.ThrowIfGreaterThan | Guard.InRange | | Empty collection | (none built-in) | Guard.NotEmpty | | Business rule | (none built-in) | Guard.Requires | | Enum not defined | (none built-in) | Guard.DefinedEnum |

Where to Guard

| Layer | Guard? | Example | |-------|--------|---------| | Public API methods | Always | Factory methods, service methods | | Internal methods called from guarded publics | Rarely | Inputs already validated upstream | | Constructor parameters | Always | DI-injected dependencies | | Configuration values | Always | Settings read from config | | Event handlers / callbacks | Always | External input boundary |

When to Use

• Every public method that accepts parameters
• Constructors receiving dependencies
• Any boundary where data enters your code from an external source

When NOT to Use

• Private methods called only from already-guarded public methods
• Hot loops where the check is proven redundant by profiling
• Simple property getters/setters (use required or init instead)

Gotchas

1. Use precise exception types: ArgumentNullException for null, ArgumentOutOfRangeException for range, ArgumentException for format/content. Never throw base Exception.
2. Include the parameter name: Always pass nameof(param) — it appears in the exception message and helps debugging.
3. Guard early, not deep: The first lines of a method should be guards. Don't intermingle them with business logic.
4. Don't guard then ignore: If you guard a parameter, use it. Dead guards are noise.
5. CallerArgumentExpression (C# 10+): For custom guards, use [CallerArgumentExpression] to auto-capture the expression name without nameof.

Advanced: CallerArgumentExpression

public static T NotNull<T>(
    T? value,
    [CallerArgumentExpression(nameof(value))] string? expression = null) where T : class
    => value ?? throw new ArgumentNullException(expression);

// Usage — no nameof needed
Guard.NotNull(order);  // Exception message includes "order" automatically

Related Skills

• Internal-by-Default Library Design (guards protect factory methods)
• Retry with Exponential Backoff (guard retry parameters)