We read a method like that from top to bottom and assume it runs in the same order: the checks first, the work last, and if the method returns early, nothing below the return has happened yet. That's usually true, but lambdas, yield and await make the compiler rewrite the code around them.

A lambda that captures a variable makes some work run too early. yield and await turn the method into a state machine, and the checks at its top fail too late. This post is mostly about that timing, but the rewrites also allocate, so we'll count those bytes too.

If you've read the .NET source, you've probably seen the BCL's fix for this: a public method Foo that does a couple of checks and then calls a private FooCore. Let's put one small method through both rewrites and see why that second method is there.

Too early: the closure

Say we look up a user by name, with the usual checks and an early exit for an empty collection. Every static method in this post lives in this Users class, even when a sample leaves the class out:

public sealed record User(string Name, bool IsActive);

public static class Users
{
    public static User? FindByName(IReadOnlyCollection<User> users, string name)
    {
        ArgumentNullException.ThrowIfNull(users);
        ArgumentException.ThrowIfNullOrEmpty(name);

        if (users.Count == 0)
            return null;

        return users.FirstOrDefault(u => u.Name == name);
    }
}

The lambda u => u.Name == name reads name, which is a parameter of FindByName. But the compiler turns the lambda into a separate method, and one method can't read another method's parameters. So the compiler creates a hidden class, called a closure, moves name into a field of that class and makes the lambda one of its methods. After that, every read of name in FindByName goes through that field, including the one in the validation.

The compiler creates the closure object when execution enters the scope of the captured variable. A parameter's scope is the whole method, so the closure is created as soon as the method starts, before any of the checks run.

You can see that in SharpLab, or in ILSpy with lambda decompilation turned off. The generated names aren't valid C# on purpose, so they can't clash with yours. The closure is <>c__DisplayClass0_0, which is why closures are also called display classes, and the lambda is <FindByName>b__0. Here's the same code with readable names:

// What the compiler generates
public static class Users
{
    private sealed class FindByNameClosure
    {
        public string? name;

        public bool Lambda(User u) => u.Name == name;
    }

    public static User? FindByName(IReadOnlyCollection<User> users, string name)
    {
        var closure = new FindByNameClosure();
        closure.name = name;

        ArgumentNullException.ThrowIfNull(users);
        ArgumentException.ThrowIfNullOrEmpty(closure.name);

        if (users.Count == 0)
            return null;

        return users.FirstOrDefault(closure.Lambda);
    }
}

The first two lines of FindByName create the closure and copy name into it, before any of the checks. Only the Func<User, bool> delegate is still created where the lambda was written, on the last line.

On .NET 10.0.12 (x64, Release), BenchmarkDotNet's [MemoryDiagnoser] shows 24 bytes per call to FindByName with an empty collection. That's the closure, allocated for a lambda that never runs, and every call that fails validation allocates it too.

Side note: when the collection isn't empty, the number depends on the runtime. On .NET 8, the call also allocates the 64-byte delegate and the enumerator that FirstOrDefault gets from the collection: 120 bytes in total for a User[] and 128 for a List<User>. On .NET 10, FirstOrDefault reads arrays and lists as spans and the JIT keeps the delegate on the stack, so only the closure's 24 bytes are left.

Fix: copy the parameter inside a block

A local declared inside an inner { } block has that block as its scope, so if a lambda captures it, the compiler creates the closure only when execution enters the block. That means we can copy name into such a local after the early return and let the lambda capture the copy instead of the parameter:

public static User? FindByName(IReadOnlyCollection<User> users, string name)
{
    ArgumentNullException.ThrowIfNull(users);
    ArgumentException.ThrowIfNullOrEmpty(name);

    if (users.Count == 0)
        return null;

    {
        string localName = name;
        return users.FirstOrDefault(u => u.Name == localName);
    }
}

The captured variable now belongs to the block, so the compiler creates the closure there, below the checks and the early return. The closure class is the same as before, except that its field is called localName:

// What the compiler generates
public static User? FindByName(IReadOnlyCollection<User> users, string name)
{
    ArgumentNullException.ThrowIfNull(users);
    ArgumentException.ThrowIfNullOrEmpty(name);

    if (users.Count == 0)
        return null;

    {
        var closure = new FindByNameClosure();
        closure.localName = name;
        return users.FirstOrDefault(closure.Lambda);
    }
}

On both .NET 8 and .NET 10, the empty path now allocates nothing, and the non-empty path allocates the same as before.

This fix is fragile, because it all depends on the braces. Without them, the scope of localName is the whole method again. The closure goes back to the first line, even though the copy is written after the return, and the empty path is back to 24 bytes. The method also allocates on entry again if the lambda reads anything else from the outer scope, like another parameter, or if another lambda in the method captures name. To a reader, the copy looks redundant, and nothing warns when someone inlines it or removes the braces.

Fix: split the method

The sturdier fix is to move the lambda out of the method. The public method keeps the checks and the early exit, and everything that captures a variable goes into a private method with the same name and a Core suffix:

public static User? FindByName(IReadOnlyCollection<User> users, string name)
{
    ArgumentNullException.ThrowIfNull(users);
    ArgumentException.ThrowIfNullOrEmpty(name);

    if (users.Count == 0)
        return null;

    return FindByNameCore(users, name);
}

private static User? FindByNameCore(IReadOnlyCollection<User> users, string name) =>
    users.FirstOrDefault(u => u.Name == name);

FindByName no longer contains a lambda, so it has nothing to capture, and the compiler leaves it as written. The closure moved into FindByNameCore:

// What the compiler generates
public static User? FindByName(IReadOnlyCollection<User> users, string name)
{
    ArgumentNullException.ThrowIfNull(users);
    ArgumentException.ThrowIfNullOrEmpty(name);

    if (users.Count == 0)
        return null;

    return FindByNameCore(users, name);
}

private static User? FindByNameCore(IReadOnlyCollection<User> users, string name)
{
    var closure = new FindByNameCoreClosure();
    closure.name = name;
    return users.FirstOrDefault(closure.Lambda);
}

The closure is still created on the first line of a method, but that method is now FindByNameCore, which only runs when the checks pass and the collection isn't empty. On both .NET 8 and .NET 10, the empty path went from 24 bytes to zero, and the non-empty path allocates the same as before.

FirstOrDefault runs the lambda during the call. Where doesn't call the lambda until someone enumerates the result, and a method you write with yield return doesn't run any of its code until then, not even the checks. That's where the timing goes wrong in the other direction.

Too late: the state machine

When a method contains yield return or await, the compiler rewrites the whole method. It generates a type, the state machine, and moves the body into its MoveNext method. The method you call becomes a stub that creates the state machine. Your checks move into MoveNext with everything else, so they run when MoveNext runs. Iterators and async methods run MoveNext at different times, so they go wrong in two different ways.

Iterators: the checks wait for the first MoveNext

Here's a method that returns every user whose name starts with a prefix, with the same kind of checks at the top:

public static IEnumerable<User> FindByPrefix(IReadOnlyCollection<User> users, string prefix)
{
    ArgumentNullException.ThrowIfNull(users);
    ArgumentException.ThrowIfNullOrEmpty(prefix);

    foreach (User user in users)
    {
        if (user.Name.StartsWith(prefix))
            yield return user;
    }
}

For an iterator, the state machine is a class that implements IEnumerable<User>. Calling FindByPrefix only creates an instance of that class and returns it. None of the code you wrote runs until someone starts enumerating. Here's the class, written by hand like the closure. The real one has more states and bookkeeping, and the IEnumerable<User> plumbing at the end is left out:

// What the compiler generates
public static IEnumerable<User> FindByPrefix(IReadOnlyCollection<User> users, string prefix)
{
    return new FindByPrefixIterator(users, prefix);
}

private sealed class FindByPrefixIterator(IReadOnlyCollection<User> users, string prefix)
    : IEnumerable<User>, IEnumerator<User>
{
    private enum State { NotStarted, PausedAtYield, Finished }

    private State state = State.NotStarted;
    private IEnumerator<User> usersEnumerator = null!;

    public User Current { get; private set; } = null!;

    public bool MoveNext()
    {
        switch (state)
        {
            case State.NotStarted:
                ArgumentNullException.ThrowIfNull(users);
                ArgumentException.ThrowIfNullOrEmpty(prefix);
                usersEnumerator = users.GetEnumerator();
                break;
            case State.PausedAtYield:
                break;
            case State.Finished:
                return false;
        }

        while (usersEnumerator.MoveNext())
        {
            User user = usersEnumerator.Current;
            if (user.Name.StartsWith(prefix))
            {
                Current = user;
                state = State.PausedAtYield;
                return true;
            }
        }

        state = State.Finished;
        usersEnumerator.Dispose();
        return false;
    }

    // GetEnumerator, Dispose and the rest of the IEnumerable<User> plumbing
}

The constructor only stores the arguments. The foreach became a while over usersEnumerator, and the yield return became three lines that store the user in Current, set the state to PausedAtYield and return true. The next MoveNext takes the PausedAtYield case and continues the loop. The checks ended up in the NotStarted case, so they run on the first MoveNext, not during the call.

So FindByPrefix(users, "") returns without complaint. The ArgumentException only shows up on the first MoveNext, maybe in a foreach three layers away, long after the code that passed the empty prefix has returned. And with an empty collection, the call still allocates a 72-byte iterator that has nothing to iterate.

Fix: split the iterator

There's no lambda this time, but the same split helps. The public method keeps the checks and gets an early exit for an empty collection, and the iterator moves into FindByPrefixCore:

public static IEnumerable<User> FindByPrefix(IReadOnlyCollection<User> users, string prefix)
{
    ArgumentNullException.ThrowIfNull(users);
    ArgumentException.ThrowIfNullOrEmpty(prefix);

    if (users.Count == 0)
        return [];

    return FindByPrefixCore(users, prefix);
}

private static IEnumerable<User> FindByPrefixCore(IReadOnlyCollection<User> users, string prefix)
{
    foreach (User user in users)
    {
        if (user.Name.StartsWith(prefix))
            yield return user;
    }
}

FindByPrefix has no yield, so the compiler leaves it almost as written. Only FindByPrefixCore turns into a stub, and its iterator class is the one from before, minus the two checks:

// What the compiler generates
public static IEnumerable<User> FindByPrefix(IReadOnlyCollection<User> users, string prefix)
{
    ArgumentNullException.ThrowIfNull(users);
    ArgumentException.ThrowIfNullOrEmpty(prefix);

    if (users.Count == 0)
        return Array.Empty<User>();

    return FindByPrefixCore(users, prefix);
}

private static IEnumerable<User> FindByPrefixCore(IReadOnlyCollection<User> users, string prefix)
{
    return new FindByPrefixCoreIterator(users, prefix);
}

The checks now run in a plain method, so FindByPrefix(users, "") throws on the spot. The [] became Array.Empty<User>(), a cached empty array, so the empty case allocates nothing. The iterator is only created when there's something to iterate.

An iterator's MoveNext waits for someone to enumerate. An async method's MoveNext starts during the call, so its checks run on time, but their exceptions still arrive late.

Async methods: the exception waits in the task

Here's FindByName again, but this time the users come from somewhere asynchronous:

public static async Task<User?> FindByNameAsync(IUserSource source, string name)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentException.ThrowIfNullOrEmpty(name);

    IReadOnlyList<User> users = await source.LoadAsync();
    return users.FirstOrDefault(u => u.Name == name);
}

public interface IUserSource
{
    Task<IReadOnlyList<User>> LoadAsync();
}

Rewritten the same way, FindByNameAsync becomes a stub that sets up the state machine and starts it:

// What the compiler generates
public static Task<User?> FindByNameAsync(IUserSource source, string name)
{
    var stateMachine = new FindByNameAsyncStateMachine
    {
        builder = AsyncTaskMethodBuilder<User?>.Create(),
        source = source,
        name = name,
    };
    stateMachine.builder.Start(ref stateMachine);
    return stateMachine.builder.Task;
}

Start calls the state machine's MoveNext right away, on the caller's thread, and the stub returns the task only after that call comes back. MoveNext holds the body of your method, and everything it has to keep between calls, like the parameters, the closure and the awaiter, is a field of the state machine. Here's MoveNext, again with some bookkeeping left out:

// What the compiler generates
public void MoveNext()
{
    User? result;
    try
    {
        if (state == State.NotStarted)
        {
            closure = new FindByNameAsyncClosure();
            closure.name = name;

            ArgumentNullException.ThrowIfNull(source);
            ArgumentException.ThrowIfNullOrEmpty(closure.name);

            loadAwaiter = source.LoadAsync().GetAwaiter();
            if (!loadAwaiter.IsCompleted)
            {
                state = State.WaitingForLoad;
                builder.AwaitUnsafeOnCompleted(ref loadAwaiter, ref this);
                return;
            }
        }

        IReadOnlyList<User> users = loadAwaiter.GetResult();
        result = users.FirstOrDefault(closure.Lambda);
    }
    catch (Exception exception)
    {
        state = State.Finished;
        builder.SetException(exception);
        return;
    }

    state = State.Finished;
    builder.SetResult(result);
}

MoveNext runs until an await actually has to wait. If the task from LoadAsync isn't finished yet, MoveNext sets the state to WaitingForLoad, asks AwaitUnsafeOnCompleted to call it again when the task completes, and returns. The second call skips the NotStarted block and picks up the result. The state machine itself doesn't allocate too early: in Release builds it's a struct, and it only moves to the heap at that await.

What makes it late is the try around the whole body of MoveNext. It catches every exception, even one thrown before the first await, and passes it to SetException, which stores it in the task that the stub returns. So FindByNameAsync(source, "") returns normally, with a task that has already faulted.

If you await FindByNameAsync(source, name) directly, you won't notice, because the exception comes out on that same line anyway. The difference shows when the task isn't awaited right away: a task stored and awaited later, a fire-and-forget call, or several calls awaited together with Task.WhenAll. In that last case, the ArgumentException comes out of await Task.WhenAll(...), away from the call that passed the empty name.

The first section's problem is in there too: the first two lines of the NotStarted block create a closure and copy name into it, before the checks. That comes from the lambda, not from async, and an iterator with the same lambda would do the same at the top of its MoveNext. This method has both a lambda and an await, so it gets both problems.

Fix: split the async method

The split fixes both problems, as long as the public method itself isn't async:

public static Task<User?> FindByNameAsync(IUserSource source, string name)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentException.ThrowIfNullOrEmpty(name);

    return FindByNameAsyncCore(source, name);
}

private static async Task<User?> FindByNameAsyncCore(IUserSource source, string name)
{
    IReadOnlyList<User> users = await source.LoadAsync();
    return users.FirstOrDefault(u => u.Name == name);
}

Now only FindByNameAsyncCore gets rewritten. FindByNameAsync stays a plain method that runs its checks and then calls the stub:

// What the compiler generates
public static Task<User?> FindByNameAsync(IUserSource source, string name)
{
    ArgumentNullException.ThrowIfNull(source);
    ArgumentException.ThrowIfNullOrEmpty(name);

    return FindByNameAsyncCore(source, name);
}

private static Task<User?> FindByNameAsyncCore(IUserSource source, string name)
{
    var stateMachine = new FindByNameAsyncCoreStateMachine
    {
        builder = AsyncTaskMethodBuilder<User?>.Create(),
        source = source,
        name = name,
    };
    stateMachine.builder.Start(ref stateMachine);
    return stateMachine.builder.Task;
}

The checks in FindByNameAsync are ordinary code now, so FindByNameAsync(source, "") throws at the call. If the arguments are valid, it returns the task from FindByNameAsyncCore. The MoveNext of that state machine is the one from before without the two checks. It still creates the closure first, but by then the checks have already passed.

Back to FooCore

Put the fixes next to each other and they all do the same thing: the checks and the cheap exits stay in a plain public method, and everything the compiler rewrites (the capturing lambda, the yield, the await) goes into a private one. The public method runs entirely during the call, so its checks throw right there and its early exits don't allocate.

That's the Foo and FooCore pair from the beginning, and it already has a name. Jon Skeet calls it the "split method" pattern in his Edulinq series, where he reimplements LINQ to Objects. The Microsoft Learn article on iterators recommends the same split: in some cases, you "split an iterator method into two different methods", one that uses return and one that uses yield return. In a few places, the .NET source explains in a comment why the pair exists.

Chunk checks its arguments, returns [] for an empty array, and only then calls the yield-based ArrayChunkIterator or EnumerableChunkIterator. A comment there says that one reason for this order is to avoid allocating an iterator for an empty array. The Where overload that passes an index to the predicate is built the same way. The plain Where doesn't use yield at all: after the same checks, it returns an iterator class like ArrayWhereIterator, so it's the same split with the second half written by hand.

On the async side, HttpClient.GetStringAsync creates and checks the request, then returns GetStringAsyncCore(...). The comment above the check explains that it runs outside the async state machine so that certain exceptions propagate even when nobody awaits the returned task. SseFormatter.WriteAsync is built the same way.

Not every second half ends in Core. When it uses yield, the BCL often calls it ...Iterator, like ArrayChunkIterator and WhereIterator, and Jon Skeet's Edulinq uses ...Impl. Some code doesn't make it a separate method at all and keeps it inside the public one as a local function. The AsyncEnumerable LINQ operators that come with .NET 10 do that in methods like AnyAsync: after the null check, they return Impl(...) and declare Impl right below as a static async local function. The same shape works for an iterator. Here's the FindByPrefix split with its second half as a local function:

public static IEnumerable<User> FindByPrefix(IReadOnlyCollection<User> users, string prefix)
{
    ArgumentNullException.ThrowIfNull(users);
    ArgumentException.ThrowIfNullOrEmpty(prefix);

    if (users.Count == 0)
        return [];

    return Core(users, prefix);

    static IEnumerable<User> Core(IReadOnlyCollection<User> users, string prefix)
    {
        foreach (User user in users)
        {
            if (user.Name.StartsWith(prefix))
                yield return user;
        }
    }
}

Core is static so that it can't capture anything. Without static, it could drop its parameters and read users and prefix straight from FindByPrefix. Because Core is an iterator, that capture would bring the closure class back, created on the first line of FindByPrefix, and the empty path would allocate 32 bytes instead of nothing. With static, any capture is error CS8421, so the closure can't come back by accident.

When to split

Not every method needs to be split. The strongest reason to split one is timing: in an iterator or an async method, the checks don't fail when the caller expects them to. A bad argument should cause an exception at the call that passed it, not in a foreach or a Task.WhenAll somewhere else, and that's reason enough for a second method.

Allocations are a weaker reason. In most code, 24 or 72 bytes is nothing. A split made only to save them pays off on a hot path where the early exit is the common case, like cache hits, empty inputs or operations that have already completed. If the early exit happens once a day, the allocation doesn't matter.

So reading a method from top to bottom doesn't always tell you when each line runs. Once you know which code the compiler moves, a Foo that does little more than call FooCore no longer looks pointless. It's a split method: Foo keeps the checks that have to happen at the call, and FooCore gets everything the compiler rewrites.

I don't think there's a deeper reason behind them than human nature. Attention runs out, and the boring lines are usually the first to lose it. Even the sharpest engineer you know writes bugs like these.

The longer I work, the more I value the compiler. It reads every line before anything runs and never gets tired, yet most of us only use it to catch typos.

I also like how much intent code can carry. Programming is mostly explaining an idea to whoever reads the code next, and in C#, types and names do a lot of that explaining. The person who wrote Find(Guid, Guid) knew which Guid goes first, but the person calling it had to guess. A UserId parameter would have told both the compiler and the colleague. Types are one of the first things we learn, and judging by how much code is built from nothing but Guid, string and bool, a lot of us stop learning about them right there.

Many junior developers try to get better by becoming a kind of Iron Man who sees every detail and knows every API by heart. I think that effort is better spent on writing code that doesn't need a superhero to get right.

Look at those three bugs again. You don't need to be clever to avoid any of them, you just need to remember which Guid goes first, that a result might be an error, and that the status needs checking. People are bad at remembering things and compilers are good at it, so when code depends on someone's memory, I'd rather give that job to the compiler. And if the compiler can't reject the wrong code outright, it can often at least warn on the exact line where the mistake is.

That said, I'm not telling you to go and rewrite your project my way. Over the years I've seen the same few problems come up again and again, and I've found a few tools that help with them. This post is me sharing those. Take the ones that fit your code, and if something in your project looks like one of my examples, that alone isn't a reason to refactor it.

It's easier to show all this with code than to argue about it, so let's start with the dumbest of the three bugs: the swapped IDs.

An ID you can't swap

It's the most boring bug there is:

public sealed class Orders
{
    public OrderSummary? Find(Guid userId, Guid orderId) => null; // the lookup itself is not the point
}

// var order = orders.Find(orderId, userId);

This compiles, runs, and returns null for the rest of your career. Both parameters are Guid, so the compiler has no way to tell them apart, and since the parameter names aren't visible at the call site, the line looks fine in review too. You find out when someone reports a missing order, and even then you stare at the line for a while.

You knew which ID was which, but nothing in the code passed that on to the compiler. A small wrapper type per ID fixes that:

public readonly record struct UserId(Guid Value);
public readonly record struct OrderId(Guid Value);

public sealed record OrderSummary(OrderId Id, UserId Owner);

public sealed class Orders
{
    public OrderSummary? Find(UserId userId, OrderId orderId) => null;
}

// orders.Find(orderId, userId);
// error CS1503: Argument 1: cannot convert from 'OrderId' to 'UserId'
// error CS1503: Argument 2: cannot convert from 'UserId' to 'OrderId'

Now the same swap gives two compile errors, one per argument. You don't have to rely on someone catching it in review anymore, and as a bonus, Find(UserId, OrderId) is easier to read.

An email you validate once

I bet you've seen this one. An email address travels from a controller through a service to a repository, and every layer checks it:

public sealed class SignupController(SignupService service)
{
    public string Register(string email)
    {
        if (string.IsNullOrWhiteSpace(email) || !email.Contains('@'))
            return "Invalid email";

        service.Register(email);
        return "OK";
    }
}

public sealed class SignupService(UserRepository users)
{
    public void Register(string email)
    {
        if (string.IsNullOrWhiteSpace(email) || !email.Contains('@'))
            throw new ArgumentException("Invalid email", nameof(email));

        users.Add(email.Trim());
    }
}

public sealed class UserRepository
{
    public void Add(string email)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(email);
        if (!email.Contains('@'))
            throw new ArgumentException("Invalid email", nameof(email));

        // insert
    }
}

There are three copies of the same check, and they already disagree, because the service trims the input and the controller doesn't. A CSV import job that calls the service directly skips the controller's check entirely. And when someone needs the domain part, they write email.Split('@')[1], which then gets copied to three more places.

Every layer checks because it doesn't trust the layer before it, and with a string that's fair. A string could have been validated a microsecond ago, or it could have come straight from a form, and there's no way to tell. This is also exactly the kind of code AI agents like to generate, since by default they defend every parameter against everything.

The fix is a type that can only hold a valid address:

public sealed record EmailAddress
{
    public string Value { get; }
    public string Domain => Value[(Value.IndexOf('@') + 1)..];

    private EmailAddress(string value) => Value = value;

    public static EmailAddress Parse(string input)
    {
        var value = input.Trim();
        var at = value.IndexOf('@');
        if (at < 1 || at == value.Length - 1 || value.IndexOf('@', at + 1) >= 0)
            throw new FormatException($"'{input}' is not an email address.");
        return new EmailAddress(value);
    }

    public override string ToString() => Value;
}

// var email = EmailAddress.Parse(form.Email);   // the one place this can fail
//
// new EmailAddress("nope");
// error CS0122: 'EmailAddress.EmailAddress(string)' is inaccessible due to its protection level
//
// var copy = email with { Value = "nope" };
// error CS0200: Property or indexer 'EmailAddress.Value' cannot be assigned to -- it is read only

Side note: the check itself is a stand-in. Real email validation is a rabbit hole and not the point here.

The constructor is private, so the only way to create an EmailAddress is through Parse, and Parse throws on anything invalid. Value has no setter, not even init, so a with expression can't get around the check either. That means every EmailAddress in the program has passed the check at some point. With that type in place, the layers look like this:

public sealed class SignupService(UserRepository users)
{
    public void Register(EmailAddress email) => users.Add(email);   // nothing to check
}

The controller calls Parse once, where the text enters the system, and nothing after that has to check again. The CSV import can't skip the check, because it has no other way to get an EmailAddress. And Domain is now a property that's always correct, because the address was validated when it was created, instead of a Split('@')[1] copied into four places.

This is what DDD calls a value object: a small type defined by its value, with its rules built in. People often use the term for any wrapper around a string, but the wrapper alone isn't the useful part. An EmailAddress refuses almost every value a string would accept, and that's why it's worth having. Being a record also gives it value equality, which is where the "value" in the name comes from: two addresses with the same text are the same address.

A payload you can't misread

EmailAddress takes care of what goes into the system. The second bug from the beginning, reading a value from a result that was actually an error, is about what a method gives back. Here's a result type that holds either a number or an error:

public sealed class UnsafeResult
{
    public bool IsOk { get; init; }
    public int Value { get; init; }      // meaningful only when IsOk
    public string? Error { get; init; }  // meaningful only when !IsOk
}

// var r = Compute();
// return r.Value;   // compiles fine when r is an error

Look at the comments. Value only means something when IsOk is true, but the type shows every field to everyone and trusts you to check first. If you forget once, you get a 0 instead of an exception, and since 0 is a perfectly believable number, it travels a few methods further before anything looks wrong.

A safer design gives out the payload only through a method that makes you handle every case:

public abstract class Result
{
    private Result() { }

    public abstract T Match<T>(Func<int, T> onOk, Func<string, T> onError);

    public static Result Ok(int value) => new OkResult(value);
    public static Result Error(string message) => new ErrorResult(message);

    private sealed class OkResult(int value) : Result
    {
        public override T Match<T>(Func<int, T> onOk, Func<string, T> onError) => onOk(value);
    }

    private sealed class ErrorResult(string message) : Result
    {
        public override T Match<T>(Func<int, T> onOk, Func<string, T> onError) => onError(message);
    }
}

// var label = r.Match(onOk: v => $"got {v}", onError: e => $"failed: {e}");
// There is no .Value to grab.

Match takes one delegate per case and calls the one that applies, so each branch gets its own payload and there's no property to misuse. Because the constructor is private, only the nested classes can derive from Result, and nobody outside can add a third case. The case classes are private as well, so outside code can't even name them, which leaves Match as the only way to get at the value.

You might ask why I don't just make the cases public and use a switch expression. The reason is that, as of C# 14, a switch can't tell when you've covered every subclass:

public abstract record ChargeOutcome;
public sealed record ApprovedCharge(decimal Amount) : ChargeOutcome;
public sealed record DeclinedCharge(string Reason) : ChargeOutcome;

public static class ChargeLog
{
    public static string Describe(ChargeOutcome outcome) => outcome switch
    {
        ApprovedCharge a => $"charged {a.Amount}",
        DeclinedCharge d => $"declined: {d.Reason}",
    };
    // warning CS8509: The switch expression does not handle all possible values of its input type (it is not exhaustive).
    // For example, the pattern '_' is not covered.
}

Both cases are handled and you still get the warning. The compiler doesn't keep track of which classes derive from ChargeOutcome, so as far as it knows there could always be another one. Locking the hierarchy down with a private constructor, like Result does, doesn't change that. The usual fix is a _ => throw arm, which turns a new case into a runtime exception that shows up somewhere, at some point. With Match, adding a case means adding a parameter, and every call site stops compiling until it handles the new case.

A state you can't forget

The same problem shows up in domain state. Say an order starts as a draft, gets paid, then gets shipped. The usual model is a status field:

public readonly record struct PaymentId(Guid Value);

public enum OrderStatus { Draft, Paid, Shipped }

public sealed class Order
{
    public OrderId Id { get; init; }
    public OrderStatus Status { get; private set; }
    public decimal Total { get; private set; }
    public PaymentId? Payment { get; private set; }      // meaningful only when Paid or Shipped
    public string? TrackingNumber { get; private set; }  // meaningful only when Shipped

    public void AddLine(decimal price)
    {
        if (Status != OrderStatus.Draft) throw new InvalidOperationException("Order is no longer editable.");
        Total += price;
    }

    public void Pay(PaymentId payment)
    {
        if (Status != OrderStatus.Draft) throw new InvalidOperationException("Order is already paid.");
        Payment = payment;
        Status = OrderStatus.Paid;
    }

    public void Ship(string trackingNumber)
    {
        if (Status != OrderStatus.Paid) throw new InvalidOperationException("Order is not paid.");
        TrackingNumber = trackingNumber;
        Status = OrderStatus.Shipped;
    }

    public void ApplyDiscount(decimal amount)
    {
        Total -= amount;   // added six months later
    }
}

Look familiar? It's UnsafeResult again in a different hat: a status, plus data that only means something for certain statuses. Each method is supposed to start with a status check, and someone has to remember to write it. AddLine, Pay and Ship have theirs. ApplyDiscount was added six months later by someone in a hurry and doesn't, so now a paid order can get cheaper after the money has already changed hands, even though the status field was correct the whole time.

Here's the same order with each state as its own type:

public sealed record DraftOrder(OrderId Id, decimal Total)
{
    public DraftOrder AddLine(decimal price) => this with { Total = Total + price };
    public PaidOrder Pay(PaymentId payment) => new(Id, Total, payment);
}

public sealed record PaidOrder(OrderId Id, decimal Total, PaymentId Payment)
{
    public ShippedOrder Ship(string trackingNumber) => new(Id, Total, Payment, trackingNumber);
}

public sealed record ShippedOrder(OrderId Id, decimal Total, PaymentId Payment, string TrackingNumber);

public sealed class Invoices
{
    public void Issue(PaidOrder order) { }   // no status check, because there is nothing to check
}

// var paid = draft.AddLine(9.99m).Pay(paymentId);
// var shipped = paid.Ship("1Z999");
//
// draft.Ship("1Z999");
// error CS1061: 'DraftOrder' does not contain a definition for 'Ship'
//
// invoices.Issue(draft);
// error CS1503: Argument 1: cannot convert from 'DraftOrder' to 'PaidOrder'

Paying an order now means turning one type into another: you call Pay on a DraftOrder, get back a PaidOrder, and nothing gets mutated. With a status field, checking that an order is Paid only tells you about that moment, since any later line could change the status. A PaidOrder has no status to change, so it stays paid for as long as you hold it. It can still go out of date compared to the database, like any snapshot, but it can never be half draft and half paid.

The checks are still there, they've just moved into the types. A draft has no Ship method, so instead of throwing at run time, draft.Ship(...) doesn't compile. Invoices.Issue asks for a PaidOrder, so its check is part of the signature. A discount method would go on DraftOrder, where a paid order can't reach it. And TrackingNumber exists only on ShippedOrder, so there's no need for "meaningful only when" comments anymore.

There's one place where you don't know the state: an order loaded from the database could be any of the three. There you need a type that can hold any of them and makes you ask which one it is. A small struct with a TryGet method per state does the job:

using System.Diagnostics.CodeAnalysis;

public readonly struct StoredOrder
{
    private readonly object _state;

    public StoredOrder(DraftOrder draft) => _state = draft;
    public StoredOrder(PaidOrder paid) => _state = paid;
    public StoredOrder(ShippedOrder shipped) => _state = shipped;

    public bool TryGetDraft([NotNullWhen(true)] out DraftOrder? draft)
        => (draft = _state as DraftOrder) is not null;

    public bool TryGetPaid([NotNullWhen(true)] out PaidOrder? paid)
        => (paid = _state as PaidOrder) is not null;

    public bool TryGetShipped([NotNullWhen(true)] out ShippedOrder? shipped)
        => (shipped = _state as ShippedOrder) is not null;
}

// StoredOrder order = store.Load(orderId);
// if (order.TryGetPaid(out var paid))
//     invoices.Issue(paid);   // fine, the compiler knows paid isn't null here

When a TryGet method returns false, there's no order to hand out, so the out parameter has to be nullable. [NotNullWhen(true)] tells the compiler what it can't work out by itself: when the method returns true, the value isn't null. If you skip the if or remove the attribute, passing paid on gets warning CS8604: Possible null reference argument for parameter 'order' in 'void Invoices.Issue(PaidOrder order)'.

It reads like Dictionary.TryGetValue and lets you ask about one state without caring about the others. The downside is that a chain of TryGet calls won't complain when a fourth state appears, while Match would break every call site. Which one to pick depends on how strict you want the compiler to be at that spot.

Modeling states as types works in other places too: builders where Build() only exists once the required parts are set, or connections that only have Query() after Open(). Whenever what you're allowed to call depends on what happened before, you can usually express that with types.

A result you can't drop

The state records have one weak spot, though, and it comes from habit:

var draft = new DraftOrder(orderId, 0m);
draft.AddLine(9.99m);              // looks like it adds a line
var paid = draft.Pay(paymentId);   // a paid order with a Total of 0

With the old Order class, order.AddLine(9.99m); on its own line was exactly right. With records, AddLine returns a new order, and this code throws it away. Nothing fails, and the customer pays nothing. C# lets you ignore a return value, and a type has no way to say "don't ignore me".

An analyzer can catch it, though, if you mark the transitions with [Pure]:

using System.Diagnostics.Contracts;

public sealed record DraftOrder(OrderId Id, decimal Total)
{
    [Pure] public DraftOrder AddLine(decimal price) => this with { Total = Total + price };
    [Pure] public PaidOrder Pay(PaymentId payment) => new(Id, Total, payment);
}

public sealed record PaidOrder(OrderId Id, decimal Total, PaymentId Payment)
{
    [Pure] public ShippedOrder Ship(string trackingNumber) => new(Id, Total, Payment, trackingNumber);
}

[Pure] (from System.Diagnostics.Contracts) says that a method has no side effects. Nothing checks that this is true, so only put it on methods that really don't have any. Rule CA1806, from the analyzers that ship with the .NET SDK, trusts the attribute: if a method is pure and nobody reads its result, the call was pointless. By default, though, CA1806 is only an IDE suggestion and never shows up in the build output, so raise its severity in .editorconfig:

[*.cs]
dotnet_diagnostic.CA1806.severity = warning

Now the lonely draft.AddLine(9.99m); gets a CA1806 warning saying the caller "calls AddLine but does not use the value the method returns". Use error instead of warning if you want it to fail the build.

Nulls you can't sneak past

[Pure] gives the tools a fact they can't figure out on their own, and nullable reference types depend on hints like that even more. With them turned on, the default flips: a reference can't be null unless its type says so with a ?. People usually give up on them at the spots where the compiler can't see something you know. Here's the classic one:

public sealed class Parser
{
    private List<string> _tokens;

    public Parser()
    {
        Reset();   // warning CS8618 on the constructor
    }

    public void Reset()
    {
        _tokens = new List<string>();
    }
}

The constructor does set _tokens by calling Reset, but the compiler analyzes one method at a time, so it doesn't see that. The constructor gets warning CS8618: Non-nullable field '_tokens' must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring the field as nullable. The usual workaround is private List<string> _tokens = null!;, and that ! is a lie the compiler will believe forever. Later someone changes Reset so it skips the assignment on some path, _tokens ends up null at run time, and the compiler says nothing because you told it not to worry.

A better option is to let Reset promise what it sets:

using System.Diagnostics.CodeAnalysis;

public sealed class Parser
{
    private List<string> _tokens;

    public Parser()
    {
        Reset();   // no warning
    }

    [MemberNotNull(nameof(_tokens))]
    public void Reset()
    {
        _tokens = new List<string>();
    }
}

The constructor no longer warns, and the compiler now holds Reset to its promise: break the assignment there and you get warning CS8774: Member '_tokens' must have a non-null value when exiting. NotNullWhen from the StoredOrder example works the same way. There are a few more for the less common cases, like MaybeNullWhen (the opposite of NotNullWhen), NotNullIfNotNull (the return value isn't null if a given argument isn't) and DoesNotReturn (the method never returns normally). They all give the compiler information it can't get from the code alone, so the warning shows up on the line that's actually wrong, not scattered across the code that uses it.

Settings objects run into the same warning, except here it's the caller who has to set the value, not the class itself:

public sealed class SmtpSettings
{
    public required string Host { get; init; }
    public int Port { get; init; } = 25;
}

// var settings = new SmtpSettings { Port = 587 };
// error CS9035: Required member 'SmtpSettings.Host' must be set in the object initializer or attribute constructor.

Without required, Host gets the same CS8618 warning, someone silences it with = "" or = null!, and the missing host shows up as a connection error three calls later. With required, forgetting to set it is a compile error.

All of this only helps if people pay attention to the warnings, and warnings tend to get ignored. So it's worth turning them into errors:

<PropertyGroup>
  <Nullable>enable</Nullable>
  <WarningsAsErrors>nullable</WarningsAsErrors>
</PropertyGroup>

Now every nullable warning is an error, and everything else in the build stays as it was. A complaint at compile time, on the line where the assumption broke, is a lot cheaper than a user finding the same bug in production.

Values nobody changes behind your back

So far, every bug came from calling something the wrong way. Another kind comes from a value changing while someone else still relies on it:

public sealed class Money
{
    public decimal Amount { get; set; }
    public string Currency { get; set; } = "EUR";
}

// var lines = new List<Money>();
// var price = new Money { Amount = 10m };
// lines.Add(price);
//
// price.Amount = 9m;   // reuse it for the next line...
// lines.Add(price);    // ...and now both lines cost 9

Whoever wrote the last two lines thought they were preparing the next price, but they were also changing the first one, since both list entries point to the same object. When you hold a mutable object, you're trusting that nobody else changes it, and nothing in the code enforces that trust.

If a value can't change after it's created, you only need to check it once, and after that you can rely on it:

public sealed record Money(decimal Amount, string Currency);

// var price = new Money(10m, "EUR");
// var discounted = price with { Amount = 9m };   // a new value; price is untouched

Positional record classes and readonly record structs get init-only properties, value equality and with for free. The immutability is shallow, though: a record with a List<T> property still hands out a list anyone can add to.

Functions can cause the same kind of trouble when they quietly change variables that don't belong to them. Here's a local function that looks harmless:

public static class Prices
{
    public static decimal Total(decimal[] prices, decimal discount)
    {
        decimal total = 0;

        foreach (var price in prices)
            total += Discounted(price);

        return total;

        decimal Discounted(decimal price)
        {
            if (price > 100m) discount = 0;   // big items are never discounted
            return price * (1 - discount);
        }
    }
}

Big items are never discounted, but neither is anything that comes after one, because Discounted quietly overwrites the outer method's discount parameter. Nothing in the loop hints at that, so to understand one line in the foreach, you have to keep the whole method in your head.

If you mark the local function static, that version stops compiling with error CS8421: A static local function cannot contain a reference to 'discount'. Anything it needs now has to be passed in:

public static class Prices
{
    public static decimal Total(decimal[] prices, decimal discount)
    {
        decimal total = 0;

        foreach (var price in prices)
            total += Discounted(price, discount);

        return total;

        static decimal Discounted(decimal price, decimal discount)
            => price > 100m ? price : price * (1 - discount);
    }
}

A static local function can't touch the enclosing method's locals, parameters or this. It gets everything through its arguments and gives back only its return value. It can still use static fields, so it isn't pure in the mathematical sense, but the compiler does guarantee that it doesn't quietly read or change the surrounding method's variables.

Don't overdo it

Please don't take this as a rule to create a new type every time something looks like it could be a discriminated union, meaning a type that is exactly one of a fixed set of cases, like Result or the order states. It depends on the case. A flag that one method checks once doesn't need a family of records and a Match method. The order states were worth it because the same check kept showing up in method after method, and forgetting it cost money.

Types also aren't completely free. They're close to it: a large modern application can have tens or even hundreds of thousands of them without anyone noticing, and in business software, code size is a number almost nobody tracks. The people who really care about it are mostly the .NET runtime developers.

Still, there is a cost, and it's mostly code size. A positional record generates equality, hashing, ToString, Deconstruct and operators you never wrote. And a readonly record struct used as a generic argument, like the key in Dictionary<OrderId, PaidOrder>, gets its own JIT-compiled copy of that generic code, because the runtime shares one copy across all reference types but compiles a separate one for each value type. More code means more pressure on the CPU's instruction cache.

You don't have to use everything in this post, but if you do, that's the price, and in most code it's a small one.

Say what you mean

Looking back at the broken versions in this post, they all have something in common. The person writing them knew something important, like which Guid is which or that an order was already paid, and kept it in their head. The fixed versions move that knowledge into a type or a signature, where the compiler can check it and the next person can read it.

There's a speaker I really like listening to, Kevlin Henney. I remember a talk where he brought up the sparring scene from The Matrix, the one where Morpheus tells Neo to stop trying to hit him and hit him. He said developers do the same with naming: instead of just calling a thing what it is, they keep trying to name it. That one stuck with me.

Code is how programmers talk to each other, and nobody can see into your head. So if something matters, put it in a type name or a method signature instead of leaving the reader to guess what you meant.