What is the principle of least astonishment, and how do you apply it to C# APIs and library design?

1. Origin

The principle (also "principle of least surprise") comes from UI and programming-language design in the 1970s–80s and is often quoted in API design: "a component should behave in a way that most users expect". Krzysztof Cwalina and Brad Abrams' Framework Design Guidelines turned it into concrete .NET conventions, and the BCL follows them closely.

2. Where expectations come from

Consistency inside a codebase often matters more than the "best" individual choice.

3. The Try pattern done right

public static bool TryParse(string? input, [NotNullWhen(true)] out Postcode? result)
public static Postcode Parse(string input)   // throws FormatException for invalid input

• Try never throws for expected failures (bad input); it may still throw for programming errors.
• Pair it with a throwing Parse for callers who expect valid input.
• [NotNullWhen(true)] lets nullable analysis know result is non-null on success.

4. Async conventions

5. Equality and value semantics

// Surprise: Equals overridden, GetHashCode not → HashSet/Dictionary misbehave
public sealed class Money { public decimal Amount; public override bool Equals(object? o) => o is Money m && m.Amount == Amount; }

// Least surprise: records give consistent Equals, GetHashCode, ==, ToString
public readonly record struct Money(decimal Amount, string Currency);

6. Analysers that encode the conventions

Enable with <AnalysisMode>Recommended</AnalysisMode> (or All) and treat warnings as errors for public libraries.

7. Versioning without surprises

• Don't change behaviour silently under the same signature; add a new method or option.
• Mark old APIs [Obsolete("Use X instead")] before removal.
• Use semantic versioning for packages; breaking changes = major version.
• Tools like Microsoft.DotNet.ApiCompat or public API analysers detect accidental breaking changes.

8. Try it yourself

1. Enable <AnalysisMode>Recommended</AnalysisMode> in a library and fix CA1068/CA2016/CA1065 warnings.
2. Review every property getter in a shared library for I/O or side effects.
3. Implement TryParse/Parse for a value object with [NotNullWhen(true)].
4. Search for methods named Get* that write data and rename or split them.
5. Add the public API analyser to a package and make a breaking change to see it flagged.

using System.Diagnostics.CodeAnalysis;

Console.WriteLine(Postcode.TryParse("6000", out var pc) ? pc.ToString() : "invalid");
Console.WriteLine(Postcode.TryParse("60A0", out _));                 // False, no exception

var repo = new CustomerRepository();
var c = await repo.GetOrCreateAsync("[email protected]");             // name says it may create
Console.WriteLine(c);

// Value semantics with consistent Equals, GetHashCode and ToString.
public readonly record struct Postcode
{
    public string Value { get; }
    private Postcode(string value) => Value = value;

    public static bool TryParse(string? input, [NotNullWhen(true)] out Postcode? result)
    {
        result = input is { Length: 4 } && input.All(char.IsAsciiDigit) ? new Postcode(input) : null;
        return result is not null;
    }

    public override string ToString() => Value;
}

public sealed record Customer(Guid Id, string Email);

public sealed class CustomerRepository
{
    private readonly Dictionary<string, Customer> _byEmail = new(StringComparer.OrdinalIgnoreCase);

    // Async suffix, CancellationToken last with a default, honest name.
    public Task<Customer> GetOrCreateAsync(string email, CancellationToken ct = default)
    {
        ct.ThrowIfCancellationRequested();
        if (!_byEmail.TryGetValue(email, out var customer))
            _byEmail[email] = customer = new Customer(Guid.NewGuid(), email);
        return Task.FromResult(customer);
    }
}