“Testability of functions which need to accept large objects as a parameter but only use a fraction of the properties of the object” just do not roll off the tongue.

We’re going to take a look at some strategies for increasing the testability of your code. Particularly when the function you’re testing requires you to mock large input objects. This blog will not discuss strategies for impure functions that require large, mocked services, as Mark Seemann has already described how to structure an impure function to extract the testable pure parts of it.

Just pass the parameters you need

// Instead of:
public static int SomeFunction(SomeLargeObject obj)
{
  return obj.SomeProp + obj.SomeOtherProp
}

// Try:
public static int SomeFunction(int someProp, int SomeOtherProp)
{
  return somePromp + someOtherProp
}

If SomeLargeObject has several required properties and complicated rules to enforce invariants, then testing SomeFunction becomes much easier if we just pass in the information it needs.

Sometimes the number of parameters gets quick long. We can pass in an object which has only these properties, but copying all the fields from the old object to the new object creates some verbose code, and it’s particularly dangerous if the function has multiple call sites.

Ideally, in our domain code we’d like to pass in our whole domain object for simplicity, but in our test code pass in just the properties the function actually needs to return a result.

The solution is something I’m calling a facet, as in “a particular aspect or feature of something”. First, we make an object that will serve as our parameter to our function, containing only the properties it needs. Then, using the features of C# we create an implicit converter from our domain object to our facet. This is what will allow us to pass in either the facet, or the domain model.

public class Account
{
 // Incredibly large domain model omitted for sanity
}

// This object contains the information needed
// to calculate loyalty, the age of the account
// and total amount spent
public record AccountLoyaltyInformation(
  DateTime CreationDate,
  decimal TotalSpent);
{   
  // create an implicit conversion from our domain model
  public static implicit operator AccountLoyaltyInformation(Account account)
    => new AccountLoyaltyInformation(account.CreationDate, account.TotalSpent);
}

public int CalculateLoyalty(AccountLoyaltyInformation loyaltyInfo)
{
  // Implementation omitted
}

// Use the parameter object directly to simplify testing
public void TestLoyaltyCalculations(Date someDate, decimal someTotalSpent, int expectedLoyaltyRating)
{
  int actualLoyaltyRating = CalculateLoyalty(new(someDate, someTotalSpent));
  actualLoyaltyRating.ShouldBe(expectedLoyaltyRating);
}

// pass in the domain object directly in the application code
public async Task<int> GetCustomerLoyalty(Guid customerId)
{
  Account account = await _db.LoadCustomerAccount(customerId);
  return CalculateLoyalty(account); // implicitly converts to 'AccountLoyaltyInformation'
}

Why not an object property?

At first it might seem like the obvious better solution is to simply make some LoyaltyInformation object a property on the Account object, and we can get rid of all this nonsense around implicit conversions.

But often, Account is a large object with a rich history of why it’s properties are subdivided the way they are, and some new feature may just have to deal with the fact that CreationDate is on Account.AuditInformation and TotalSpent is on Account.PurchaseHistory.

I was taking a look at Tailwind

After all the discussion, and having my eye on it for quite some time, I decided to finally take a look at Tailwind CSS, and while watching a video to get a high level view of it, the creator said something that started a free fall into my latest obsession. "I usually reserve Tailwind for larger projects and use Pico for small projects and prototypes"

Now I had something else to look up, and boy am I glad I did. You see, I love semantic html. I pine for the days when navbars were made with <nav>. When we knew that just because something had an onclick event, it didn't mean you should use it as a <button>. The days when, if you had tabular data, you put that in a <table>!

So you can imagine my delight when I found Pico CSS, a small, mostly classless stylesheet that used semantic html to build simple, but very pleasant web UI's. I couldn't stop myself from pulling up VS Code, and tooling up a quick greeting page for a sample Blackjack app.

No joke, the following took me < 5 minutes:

In about a half hour, I'd tooled out most of the actual game UI:

With a little work and my own custom CSS, I probably could have gotten unicode card characters to work with a better font and larger size, but out of the box, they didn't render well with Pico.

Okay, So Now What

None of this means anything if we can't actually play BlackJack, let's try and add this to a Blazor app. A simple blackjack app has no persistence, so as standalone WASM app will work fine for our purposes.

My first approach was to continue using Pico as I had been, simply linking the cdn. When I did a few things felt... off.

Firstly, the padding between my bank/betting <header> and my <main> playmat looks all wrong, and there was this strange white border around the "Bank $975" <h1>.

The weird outline kept going away as soon as I clicked anywhere on the page, so I decided to tackle the padding first.

Semantic Layout and Root Elements

Pico is built around semantic html, and by default it applies styles to <header>, <main>, and <footer> tags that are immediate children of <body>. This works great for static html, this does not work great for Blazor WASM. Blazor needs a root element, and by default it's a <div id="app"> at the top of <body>, which means when my content was moved to the Home component, <header> and <main> where immediate children to a <div>, so the styling wasn't correct.

Pico has a fix for this.

When you import Pico CSS with Sass, you can specify your root element, what we need in Blazor is something like this:

@use "pico" with (
    $semantic-root-element: "#app",
    $enable-semantic-container: true,
);

Just one problem. I'm not using Pico with Sass.

Sassy Blazor

I didn't want to hack together a solution. I am after all trying to lay the groundwork for a system which will help me reliably get up and running with my next side project. So I set out to find out how adding Sass to Blazor works. I found this article written by Adrian Hall, and it was just what I was looking for. Using this as a guide, I added the WebCompiler extension for Visual Studio, and compiled a sass file into app.min.css, which I have since renamed customPico.min.css

Once that was done, I needed to get the Pico .scss source files, and they provided instructions on how to do this with npm or yarn.

npm install @picocss/pico

Just one problem. I don't want to use npm or yarn.

First, I simply went to the Pico CSS github repo, and downloaded the latest release, and stuffed the .scss files into my project. Worked well enough, but not exactly maintainable.

LibMan to the Rescue

While clicking around my project, I noticed something very curious I've never noticed before.

Recent versions of Visual Studio ship with a client side library manager, all I had to do was point it at the unpkg source, do a quick search for @picocss and I even got to select only the .scss files I needed instead of the whole package.

Sure the resulting folder structure was picocss/pico/scss but I can live with that all things considered.

Adding the finishing touches

Once I had that setup, I ended up with a very short customPico.scss file

@use "picocss/pico/scss/pico" with (
    $semantic-root-element: "#app",
    $enable-semantic-container: true,
    $theme-color: "cyan"
);

Then, I linked it to the index.html file of my wwwroot folder

<link rel="stylesheet" href="customPico.min.css" />

That just left that weird white border, and that turned out to be a one line fix after consulting the oracles on r/Blazor, simply removing this from my App.razor file did the trick

<FocusOnNavigate RouteData="@routeData" Selector="h1" />

And now my Blazor app matched my static html

Conclusion

I plan on building out the rest of this BlackJack app using Blazor and Pico CSS, but in getting set up I learned some valuable lessons for using this wonderful classless (read: less classes) css framework with Blazor.

This hasn't prevented many an ambitious programmer from attempting to write their own Result<T> type, and why wouldn't you? Exceptions are unexpected, and expensive. A type that communicates to the programmer that failure is a possibility and that they should be prepared to handle it will only ensure good coding practices, right? Sadly, this isn't always the case.

Many codebases end up littered with Result<T> types and throw many exceptions. The object causes friction and is most often ignored. This leaves developers with a bad taste in their mouth about the Result<T> type. Some of this is avoidable, and some of this, sadly represents a shortcoming in the C# language itself.

By understanding where developers go wrong, and where they language falls short, we can create a more robust Result<T> type that stands a much better chance of justifying the additional complexity.

Where C# Falls Short: No Safe Unwrap

Some languages, like Rust, provide an elegant way to unwrap Result<T> types. In the case of Rust, the ? operator will unwrap a Result<T> and return the value. If the Result<T> represents an error, the function immediately early returns the error. Thus, any function that uses the ? operator in Rust, must itself return a Result<T> type.

fn read_file_contents(filename: &str) -> Result<String, io::Error>
{
    // Open the file, using `?` to propagate errors
    let mut file = File::open(filename)?;

    let mut contents = String::new();
    // Read the file contents into a string, using `?` to propagate errors
    file.read_to_string(&mut contents)?;
    Ok(contents) 
}

This will feel very familiar to C# developers who have a similar unwrap mechanic for Task<T>: async/await. the await keyword unwraps a task, and any function which uses await must be marked async and itself, return a task.

public async Task<string[]> ReadFileContents(string path)
{
    // read all lines using `await` to unwrap an asynchronus function
    var lines = await File.ReadAllLinesAsync(path);
    return lines;
}

Because a Result<T> type is not part of the BCL, there's no reason (or good way really) to add a similar operator to unwrap a Result<T> in C# and propagate any errors. Sadly, the following is not valid C#

public Result<string> GetUsername(Guid userId)
{
    // use `?` to propogate errors
    var user = _db.Find<User>(userId)?
    return user.Name;
}

Where Developers Go Wrong: The Unsafe Unwrap

In an effort to make their Result<T> types easier to use, many developers will add an unsafe unwrap. Usually this takes the form a property called Value which simply throws if the Result<T> represents a failure. The following examples for the rest of this article are using C# 12 with nullable enabled, and all warnings treated as errors.

// A simple Result<T> with an unsafe unwrap called `Value`
public class Result<T>
{
    private readonly T? _value;
    private readonly Exception? _exception;
    private Result(T? value, Exception? exception)
    => (_value, _exception) = (value, exception);

    public static Result<T> Success(T value) => new(value, exception: null);
    public static Result<T> Failure(Exception ex) => new(value: null, ex);

    // The unsafe unwrap
    public T Value => _value ?? throw ex;
}

If the option to simply "get the value out" of a Result<T> is there, developers will take it. They will take it and the code will work, until one day it doesn't. The entire reason for switching to a Result<T> type is lost. You're carefully wrapping return values in a type that prepares for failure, only for the calling code to assume success anyway.

What can we do?

Understanding the language shortfalls, and the pitfalls of an unsafe unwrap, is it possible to make a Result<T> worth using in C#? That answer to that will always be subjective, but I believe we can do better than the example above.

Match/Switch Functions

How do you best get the value out of a Result<T>? One way is to flip the question, or "How do you best inject behavior into a Result<T>" By providing Match/Switch functions we can require that calling code provide a path forward in both the case of a success or a failure. Here is an implementation of this, and an example of its usage

public record Error(string Message);

public class Result<T>
{
    private readonly T? _value;
    private readonly Error? _error;

    private Result(T? value, Error error)
    => (_value, _error) = (value, error);

    public static Result<T> Success(T value) => new(value, null);
    public static Result<T> Failure(Error error) => new(null, error);

    public TOut Switch<TOut>(
      Func<T, TOut> success,
      Func<Error, TOut> error)
    => _value is not null
        ? success(_value)
        : error(_error!);
}

// Usage
Result<User> userResult = GetUser(userId);
string userName = userResult.Switch(
    success: user => user.Name,
    error: err => $"Unable to find user: {err.Message}");

return userName;

This doesn't have an unsafe unwrap, but it can be a little awkward in an imperative codebase, which describes quite a bit of C# code. To address this, we can rely on subclasses and pattern matching

Subtypes and Pattern Matching

C# pattern matching provides a powerful and straight forward way to ask about the runtime type of an object and capture a typed reference to that object. This makes it easy for use to check for a successful Result<T> with a simple if statement and use the successful value in a compile checked way.

public record Error(string Message);
public abstract class Result<T>
{
    public static Result<T> Success(T value) => new Success(value);
    public static Result<T> Failure(Error error) => new Failure(error);
}

public class Success<T> : Result<T>
{
    public T Value { get; }
    internal Success(T value) => Value = value;
}
public record Failure<T> : Result<T>
{
    public Error Error { get; }
    internal Failure(Error error) => Error = error;
}

// Usage
Result<User> userResult = GetUser(userId);
if (userResult is Success<User> success)
{
    return success.Value.Name;
}

Unfortunately, there isn't a great way to tell the compiler that if a Result<T> instance isn't a Success<T> type, then it must be a Failure<T> type. The lack of discriminated unions is why we're in this pickle to begin with. Still however, we can press on and refine this type further

Implicit operators

We can clean up our static factory methods with implicit conversions, this if a function's return type is Result<T> we can simply return a T or an Error

public abstract class Result<T>
{
    public static implicit operator Result<T>(T value)
    => new Success(value);

    public static implicit operator Result<T>(Error error)
    => new Failure(error);
}

// Usage
public static Result<decimal> Divide(decimal numerator, decimal denominator)
{
    if (denominator == 0) return new Error("Cannot divide by zero");
    return numerator / denominator;
}

Adding a Safe Unwrap

Next let's try and add a safe unwrap (or at least to most elegant one that C# will let us) We want failure to be the true condition so we can early return the error. We'll use the nullable branch analysis to indicate to the client code when out parameters are or are not null.

public abstract class Result<T>
{
    // Omitted

    public abstract bool UnwrapFailed(
        [NotNullWhen(true)]
        out Error? error,
        [NotNullWhen(false)]
        out T? value);
}


public class Success<T> : Result<T>
{
    public override bool UnwrapFailed(
        [NotNullWhen(true)]
        out Error? error,
        [NotNullWhen(false)]
        out T? value)
    {
        error = null;
        value = Value;
        return false;
    }
}
public record Failure<T> : Result<T>
{
    public override bool UnwrapFailed(
        [NotNullWhen(true)]
        out Error? error,
        [NotNullWhen(false)]
        out T? value)
    {
        error = Error;
        value = null;
        return true;
    }
}

// Usage
public Result<string> AssembleGreeting(Guid greetingId, Guid nameId)
{
    Result<string> greetingResult = LoadGreeting(greetingId);
    Result<string> nameResult = LoadName(nameId);

    if (greetingResult.UnwrapFailed(out var error, out var greeting))
        return error; // error is not null here
    if (nameReuslt.UnwrapFailed(out error, out var name))
        return error // error is not null here

    // neither greeting or name are null here
    return $"{greeting}, {name}!";
}

Conclusion

C# is a high ceremony language, and there are limits to how succinctly we can express certain concepts and structures that come naturally to other languages like Rust or F#, but with this in mind we can still craft a result that achieves its goal: forcing the calling code to deal with any potential errors at compile time.

Here are some fun exercises when crafting your own result types:

• Add a map/select function

• Extend the map/select function to automatically flatten (Result<Result<T>> becomes Result<T>)

• Add a way for a Result<Task<T>> to be awaited returning Result<T>

• Add an equality operator which respects referential transparency

  • Two Result<int> objects which both contain the same number should be equal

  • A Result<int> which is a Success<int> that holds 5 should be equal to an int which holds 5

To that end, this post aims to show an example of a lightweight, yet powerful Blazor modal, built on top of the html <dialog> element.

The Dialog Element

HTML has out of the box, native dialog element and modal support with just a bit of JavaScript (and our implementation will only use a small amount of this). Let's take a look at the dialog element:

<dialog open>
    <h1>Hello World!</h1>
    <p>This is an open dialog</p>
</dialog>

This creates a dialog that is always open. From here it's trivial to use a conditional to show or hide this in Blazor:

@if (ShouldShowDialog)
{
    <dialog open>
        <h1>Hello World!</h1>
        <p>This is an open dialog
    </dialog>
}

This works, and it's a very "Blazor" way to go about this, but it isn't a modal. It's a dialog, a pop up even, but it doesn't disable the rest of the view, or have other behaviors we typically associate with modals. This modal functionality of the dialog element is available via JavaScript:

const dialogRef = document.querySelector('dialog');
dialogRef.showModal();
dialogRef.close();

If we want this behavior in Blazor, we'll have to utilize the built in JavaScript Interop. The IJSRuntime interface lets us call a JavaScript function asynchronously, so let's add a couple utility methods to do that in a file we will call modal.js

function showModal(modal) { modal.showModal(); }
function closeModal(modal) { modal.close(); }

That's it! Once we've served this up with the rest of our source files, we can craft the following Blazor component, Modal. First the template:

<dialog @ref=DialogRef>
    @ChildContent
</dialog>

I did say this control was going to be very lightweight. We only add 2 things to the dialog element. First we capture a reference to this element called DialogRef and second, we render any child content that was passed to us, in the dialog element. Let's take a look at the code behind file.

public partial class Modal
{
    [Inject]
    public required IJSRuntime JS { get; init; }

    ElementReference DialogRef;

    [Parameter]
    public bool IsOpen { get; set; }
    private bool _isOpen;

    [Parameter]
    public required RenderFragment ChildContent { get; set; }

    protected override Task OnParametersSetAsync()
    {
        await ToggleModal();
        await base.SetParametersAsync(parameters);
    }

    private async Task ToggleModal()
    {
        if (_isOpen == IsOpen) return;

        string jsCommand = IsOpen ? "showModal" : "closeModal";
        await JS.InvokeVoidAsync(jsCommand, DialogRef);
        _isOpen = IsOpen;
    }
}

First, we inject a reference to the IJSRuntime so we can call our JavaScript functions from earlier. Then we provide a field to store the reference to our dialog element. We take in two parameters, IsOpen and ChildContent. ChildContent will contain whatever inner elements were defined when this component was used, IsOpen is the binding we've given the client to determine whether the modal should show or hide.

You may notice the _isOpen backing field doesn't really back the auto-property. Component parameters are recommended to be auto properties, but we need to track the actual state of the modal, not just what our client is requesting the state to be. Because the input parameter is an auto-prop, we can't react to the value changing in the setter, so we override the OnParametersSetAsync() method to call our own ToggleModal().

It's important to note that just because OnParametersSetAsync() is called, it doesn't necessarily mean any of the values have changed, so we check for this case and early return if we don't have anything to do. In the case that the value of IsOpen did change, we execute the correct JavaScript function, passing in our dialog reference as a parameter, and then update our actual state, _isOpen to match the client requested state.

Seriously, That's it.

And just like that, we're ready to put this component in action. Let's drop this component on a page and see how it's used

@page "/"

<PageTitle>Home</PageTitle>

<h3>This is a page</h3>
<button @onclick="ShowModal">Show Modal</button>

<Modal IsOpen=ShouldShowModal>
    <h3>This is a modal</h3>
    <button @onclick="CloseModal">Close Modal</button>
</Modal>

public partial class Home
{
    public bool ShouldShowModal { get; set; } = false;

    public void ShowModal()
    {
        ShouldShowModal = true;
    }
    public void CloseModal()
    {
        ShouldShowModal = false;
    }
}

We throw a button on the page to show the modal, and then define some content for the modal which includes a button to close the modal. We toggle this by toggling the value of ShouldShowModal and the Modal component takes care of the rest.

While we have provided a functional modal, I think it's important to note what we haven't done. We haven't pulled in some bloated and/or restrictive 3rd party component library, we haven't added layers of elements and divs between the parent component and the modal content, and we haven't limited the users control over the modal style, and contents. This latter feature really made this design shine when I tried to take the next step of functionality the HTML dialog element offers: form return values

Getting Data Out

If we take a look at the documentation example for the dialog element from MDN, obtaining and returning the value of form data is a complex process when compared to the showModal() and close() functions we used previously.

<dialog id="favDialog">
  <form>
    <p>
      <label>
        Favorite animal:
        <select>
          <option value="default">Choose…</option>
          <option>Brine shrimp</option>
          <option>Red panda</option>
          <option>Spider monkey</option>
        </select>
      </label>
    </p>
    <div>
      <button value="cancel" formmethod="dialog">Cancel</button>
      <button id="confirmBtn" value="default">Confirm</button>
    </div>
  </form>
</dialog>
<p>
  <button id="showDialog">Show the dialog</button>
</p>
<output></output>

🤢

const showButton = document.getElementById("showDialog");
const favDialog = document.getElementById("favDialog");
const outputBox = document.querySelector("output");
const selectEl = favDialog.querySelector("select");
const confirmBtn = favDialog.querySelector("#confirmBtn");

// "Show the dialog" button opens the <dialog> modally
showButton.addEventListener("click", () => {
  favDialog.showModal();
});

// "Cancel" button closes the dialog without submitting because of [formmethod="dialog"], triggering a close event.
favDialog.addEventListener("close", (e) => {
  outputBox.value =
    favDialog.returnValue === "default"
      ? "No return value."
      : `ReturnValue: ${favDialog.returnValue}.`; // Have to check for "default" rather than empty string
});

// Prevent the "confirm" button from the default behavior of submitting the form, and close the dialog with the `close()` method, which triggers the "close" event.
confirmBtn.addEventListener("click", (event) => {
  event.preventDefault(); // We don't want to submit this fake form
  favDialog.close(selectEl.value); // Have to send the select box value here.
});

🤮

So, I set about doing what I thought I should do; encapsulating all of this and making it easier for a Blazor developer to use. And after a few hours of struggling, it dawned on me: I already had

The same trick I used to pass a button (whose click handler I had bound to a local function) into the modal would work for, in theory, any content. Let's modify our home page example one more time and test my hunch.

@page "/"

<PageTitle>Home</PageTitle>

<h3>This is a page</h3>
<button @onclick="ShowModal">Show Modal</button>

<Modal IsOpen=ShouldShowModal>
    <h3>This is a modal</h3>
    <!-- Add an input element and bind it's value to a property called 'Input' -->
    <input type="text" @bind-value=Input />
    <button @onclick="CloseModal">Close Modal</button>
</Modal>

public partial class Home
{
    public bool ShouldShowModal { get; set; } = false;
    // Add a string property called Input
    public string Input { get; set; } = string.Empty;

    public void ShowModal()
    {
        ShouldShowModal = true;
    }
    public void CloseModal()
    {
        Console.WriteLine($"Input: {Input}");
        ShouldShowModal = false;
    }
}

I tested this and was pleasantly surprised when, in the end, it did turn out to be that simple. The input element binds to our Input even as part of the modal, so the value is already updated when we click close. No need to mess around with form actions, submit values, confusing callbacks or preventing default actions. An entire form, bound to a property of the parent component, can be put into the Modal content.

Conclusion

Whenever I encounter some difficulty, the solution is often "It's easier than I'm making it", and web development is no exception to this rule. In our example here, we've created a modal control that is flexible and powerful enough to be shared throughout your entire application, but small enough to fit in your head.

What do I mean by exception free? Not only will the object never throw an exception, but it will not allow you to try and remove an item from top of it when none exists. This is due to not only it's design, but also that the stack is itself, an extremly simple data type (we will see in a later post how much harder this is with the Stack's opposite, a Queue)

The Status Quo

First, let's look at the promises made by the System.Collections.Generic.Stack<T>, specifically the Pop() method

Returns

T

The object removed from the top of the Stack<T>

Exceptions

InvalidOperationException The Stack<T> is empty.

This object places the burden on the client code to check whether or not the stack has items in it, in order to ensure that they do not experience an exception. Of course, no stack can Pop() an item which does not exist, but is it possible to do better than a runtime exception? We could return null, but can we do better yet still? As it so happens, we can.

The method does not exist

If the stack is empty, the method (Pop()) does not exist. Let's see how we can achieve this with an abstract base class, and two inherited sub classes

public abstract class Stack<Data> { }

public class EmptyStack<Data> : Stack<Data>
{
    internal EmptyStack() { }
}

public class NonEmptyStack<T>
{
    public Top Data { get; }
    private readonly Stack _rest;

    internal NonEmptyStack(Data top, Stack rest)
    {
        Top = top;
        _rest = rest;
    }

    public Stack Pop() => _rest;
}

First, let's note that this Stack is immutable. Which is to say that when you Pop() you are not removing the top item from this stack, but rather getting back a stack that has all the items except for the top of this one.

This is how we achieve an exception free Top and Pop(), we hide the method behind a type which is guaranteed to have at least one item, and therefore can return the Top, and execute a Pop() without exception.

We only need to add a little bit more code to complete this Stack, namely the Push() method, since currently there is no way of getting data into the Stack. Let's do that now.

public abstract class Stack<Data>
{
    public static readonly Stack<Data> Empty = new EmptyStack<Data>();
    public Stack<Data> Push(Data data) => new NonEmptyStack(data, rest: this);
}

public class EmptyStack<Data> : Stack<Data>
{
    internal EmptyStack() { }
}

public class NonEmptyStack<T>
{
    public Top Data { get; }
    private readonly Stack _rest;

    internal NonEmptyStack(Data top, Stack rest)
    {
        Top = top;
        _rest = rest;
    }

    public Stack Pop() => _rest;
}

As before our Push() method respects the fact that our stack is immutable. It returns a new Stack, which has all the items before, except with the new data as the Top of the Stack

Putting it to work

Let's use this stack to execute a simple string reverse. We try to pattern match the abstract Stack to the concrete NonEmptyStack and as long as we can successfully do so, we add the Top character to the reversed string. We then execute a Pop() and assign the returned Stack to our stack variable so as to move toward the EmptyStack, which will break the loop.

string hello = "Hello World";
Stack<char> stack = Stack<char>.Empty;
string olleh = string.Empty;

foreach(char c in hello)
{
    stack = stack.Push(c);
}

while(stack is NonEmptyStack<char> nonEmpty)
{
    olleh += nonEmpty.Top;
    stack = nonEmpty.Pop();
}
Console.WriteLine(olleh)

Conclusion

By taking advantage of immutability, a small amount of inheritance, and pattern matching, we've designed a type that will catch any attempt to read an empty stack not in Prod, QA or even in automated tests, but at the time of compilation.

But with great power, comes great responsibility, and IEnumerable<T> has it's fair share of quirks to trip up unsuspecting developers.

It's an Enumerable, not a Collection

While we often use IEnumerable<T> as a way to pass around collections, especially if we aren't picky about the underlying data structure. Maybe it's an T[], maybe it's a List<T>. We don't know and we (allegedly) don't care.

But there are lots of objects that implement the IEnumerable<T> interface and they aren't collections, and thus don't behave how we might expect them to. Often times developers will be unaware that these concrete types are in their codebases, assuming that whatever IEnumerable object they are passing around represents an actual collection. Even if you've always specified a list or array, something as simple as using LINQ can open the door to some of these other types.

These types can get us in to trouble by assuming more than the IEnumerable<T> interface promises.

Some Enumerables are lazy

Consider the following code:

public class Batter
{
  public string Name { get; }
  public bool IsAtBat { get; private set; }
  public bool IsOnDeck { get; private set; }

  public Batter(string name)
  {
    Name = name;
    IsOnDeck = false;
  }

  public void MarkAsOnDeck()
  {
    IsOnDeck = true;
  }

  public void MarkAsAtBat()
  {
    IsOnDeck = false;
    IsAtBat = true;
  }
}

public class BattingOrder
{
  public IEnumerable<Batter> BattingOrder { get; }

  public BattingOrder(IEnumerable<string> battingOrderNames)
  {
    BattingOrder = CreateBatters(battingOrderNames);
    BattingOrder.First().MarkAsAtBat();
    BattingOrder.Skip(1).First().MarkAsOnDeck();
  }

  public IEnumerable<Batter> CreateBatters(IEnumerable<string> battingOrderNames)
    => battingOrderNames.Select(name => new Batter(name));

  public Batter GetCurrentBatter()
    => BattingOrder.First(batter => batter.IsAtBat);
}

This code contains a bug, but not in any of the domain logic that's expressed.

The first Batter in the batting order should be at bat. The second Batter in the batting order should be on deck.

But when GetCurrentBatter() is called, the function fails. It can't find a batter that is currently at bat.

How can that be? We created the IEnumerable<Batter> instance, took the first one and marked it as at bat, and took the second one and marked it as on deck.

The key is right here

  public IEnumerable<Batter> CreateBatters(IEnumerable<string> battingOrderNames)
    => battingOrderNames.Select(name => new Batter(name));

In this method we use the Select() method to convert an enumerable of string, to an enumerable of Batter, and that's just it. We have an enumerable of batters which makes no guarantees about being a collection. In this specific case, the returned enumerable is lazy. Meaning every time we iterate through it (or call some specific LINQ methods on it) we're going to re-execute the mapping, which means we're constantly getting new references to Batter objects.

When we call this method here

  public BattingOrder(IEnumerable<string> battingOrderNames)
  {
    BattingOrder = CreateBatters(battingOrderNames);
    BattingOrder.First().MarkAsAtBat();
    BattingOrder.Skip(1).First().MarkAsOnDeck();
  }

We're creating a lazy enumerable, then enumerating it twice. We're grabbing the first enumeration, then the second time, we're creating a new enumerable that skips the first enumeration, and then enumerating it to grab the second one, but remember each time we enumerate the BattingOrder enumerable, we create new instances of Batter objects. Meaning the "first" Batter we skip over in the last line, isn't the same Batter instance we marked as at bat on the previous line.

So finally when we call this method

public Batter GetCurrentBatter()
    => BattingOrder.First(batter => batter.IsAtBat);

We're enumerating the enumerable again, creating a whole new set of Batter instances, none of which have been marked as at bat. This seemingly straight forward and readable code, contains a very hard to spot bug, that causes it to always fail.

What to do instead

What's the solution to avoiding these kinds of errors? If we know we're going to mutate an object (such as marking a Batter as at bat), then we must necessarily have a constant reference to the object being mutated. To ensure that any enumerable we obtain will preserve these references, it's a good idea to copy the enumerable into a private collection, which we know will preserve instances. In our case, we need just a single method call to fix our error.

  public BattingOrder(IEnumerable<string> battingOrderNames)
  {
                                                    //Copy enumerable into a list
                                                    //to preserve references
    BattingOrder = CreateBatters(battingOrderNames).ToList();
    BattingOrder.First().MarkAsAtBat();
    BattingOrder.Skip(1).First().MarkAsOnDeck(); 
  }

With this change, even though the BattingOrder variable is still types as an IEnumerable<Batter> we know that the object itself is an instance of List<Batter> which means we can be confident that calling .First() will always return the same object instance, that is, the first item in the list.

If you get passed an IEnumerable<T> as a parameter, it's almost always a good idea to call .ToList() or .ToArray() on it before assigning to variable, property or field. Not only does this ensure our reference isn't mutated by someone else, we also know that any mutations we might perform will persist.

if (someCondition is true)
{
  // Do a thing
  // Do more things
  // do a final thing
  return result;
}
else
{
  return new Failure();
}

Now most people will be quick to spot that we don't need the else, since the IF block returns and we can save a few lines since the if block does an early return

if (someCondition is true)
{
  // Do a thing
  // Do more things
  // do a final thing
  return result;
}
return new Failure()

But if we invert our condition we can early return from the else block which is considerable shorter than the if block

if (someCondition is false) return new Failure();

// Do a thing
// Do more things
// do a final thing
return result;

This can be done anytime the blocks result in a method return, and the else block is shorter than the if block. Consider the following function to calculate if a year is a leap year. (A leap year is a year which is divisible by 4, but not 100 unless it's also divisible by 400)

public bool is LeapYear(int year)
{
  if (year % 4 == 0)
  {
    if (year % 100 == 0)
    {
      if (year % 400 == 0)
      {
        return true;
      }
      else
      {
        return false;
      }
    }
    else
    {
      return true;
    }
  }
  else
  {
    return false;
  }
}

This is the fully written out leap year algorithm with if and else for every condition. Notice that the else blocks all immediately return, and the first two if blocks have more code (the subsequent if blocks). We can apply our inversion rule to clean this up.

if (year % 4 != 0) return false;
if (year % 100 != 0) return true;
if (year % 400 != 0) return false;
return true;

If we replace the boolean expressions with some named extension methods and literals with constants, this code becomes very clear

if (year.IsNotDivisibleBy(4)) return NOT_LEAP_YEAR;
if (year.IsNotDivisibleBy(100)) return LEAP_YEAR;
if (year.IsNotDivisibleBy(400)) return NOT_LEAP_YEAR;
return LEAP_YEAR;

The O.G. Singleton

In computing it can often be beneficial to work with lists. They are null-safe by default as an empty list is always valid. From time to time we will expect that a list we are working with will contains one and only one value. The correct mathematical term for this is Singleton, a term which may be confusing now given the rise in popularity of IoC containers and service lifetimes, but take this as another reminder that context always matters.

Out of the box, LINQ gives us two methods for accessing the single item in a singleton: .Single() and .SingleOrDefault(). This has made me very angry and should be widely regarded as a bad move.

Single()

IFF the list contains a single item (or a single item matching a given predicate) Single() will return that item. Else, this method will throw an exception. Which is great for halting program execution, but not so great for error handling. We have methods of proving that a list contains only one item to us and other developers, but not great ways of proving it to the compiler.

if (items.Count() != 1) return;

// A little while later
return items.Single();

In the example above we know we've checked and that single will not throw, but the compiler is unaware of this assumption, and so, if the check ever gets removed, there's nothing letting the developer know that this assumption is not longer true. It's possible to solve this with a type

public record Singleton<T>
{
  public T Item { get; }
  private Singleton(T item) => Item = item;
  public bool TryParse(
    IEnumerable<T> list,
    [NotNullWhen(true)]
    Singleton<T>? singleton)
  {
    singleton = null;
    if (list.Count() != 1) return false;

    singleton = new(list.Single());
    return true;
  }
}

Yes, yes, I know I've used Single() in the type I've said would let us stop using Single() but the enforcement of this constraint is the raison d'etre of this type and so I think it's pretty clear to later developers that remove the check here is a breaking change. This is a perfectly workable solution for older .NET code, but we can (and will) do better later on.

SingleOrDefault()

A popular alternative, which does not throw is SingleOrDefault() which will always return a value. If the list is a singleton, it will return the single item, if not it will return the default (null for reference types). Combined with nullable enabled, and treating warnings as errors, the compiler will force a null check for you, but that isn't always the case.

Enter C# 11

List patterns were introduced in C# 11, and they have come to the rescue here. We now have a compiler safe way to enforce either A) that a list is a singleton, or B) that the developer has handled all alternatives.

var singleItem = list switch
{
  [] => HandleEmptyList(),
  [var item] => item,
  [var first, var second, ..] => HandleListWithMultipleItems(),
};

The compiler is now completely aware of the assumption we are making. Therefore if any of the cases are removed, it will give us an error. Well, a warning that you really should be considering an error.

We can adopt this to a variety of error handling methods, below are examples for Try, error handling delegates, and Result types.

public static bool TrySingle<T>(
  this IEnumerable<T> list,
  [NotNullWhen(true)]
  out T? item)
{
  item = list switch
  {
    [] => null,
    [T singleValue] => singleValue,
    [T first, T second, ..] => null
  };
  return item is not null;
}

public static T? Single(
  this IEnumerable<T> list,
  Action<string> error)
{
  private T? fail(string errorMsg)
  {
    error(errorMsg);
    return null;
  }

  return list switch
  {
    [] => fail("The list is empty"),
    [T singleItem] => singleItem,
    [T fist, T second, ..] => fail("The list contains multiple entries")
  };
}

public static Result<T> ParseSingle(this IEnumerable<T> list)
=> list switch
{
  [] => new Error("The list is empty"),
  [T singleItem] => singleItem,
  [T first, T second, ..] => new Error("The list contains multiple entries")
};

Note that while each of these methods don't present a significant value from the outside over something like SingleOrDefault(), they still have a compiler checked assumption and are thus more resistant to being broken accidentally by later developers.

In your domain code, it's likely much more appropriate to write the switch expression out in it's entirety as your domain likely has rules and processes for handling this failed assumption, and if it does not, go check with your customer to find out if it should.

Constructors

First we have the constructor. It's worth noting that whatever method you expose to your clients, somewhere, somehow a constructor is being called. A constructor allows us to communicate and enforce at compile time which information is required via the parameter list. Unfortunately the constructor gives us only a single method of enforcing constraints which is throwing an exception when they are violated.

public class Dimensions
{
  public decimal Length { get; }
  public decimal Width { get; }
  public Dimensions(decimal length, decimal height)
  {
    if (Length <= 0) throw new ArgumentException("Must have a positive length.")
    if (Height <= 0) throw new ArgumentException("Must have a positive height.")
    Length = length;
    Height = height;
  }
}

This is great for aborting program execution immediately, but not a great way to handle errors. Note here as well that if a client sends us a non-positive length AND height, only the first exception will be hit. Making this method unsuitable for revealing all initialization errors.

Initializers

Object initializers were added as a form of syntactic sugar to the language and were very simple early on. Here is an example of the initial offering in C# 3

public class Dimensions
{
  public decimal Length { get; set; }
  public decimal Width { get; set; }
}

// Pre C# 3
Dimensions d = new Dimensions();
d.Length = 2m;
d.Width = 1m;

// Since C# 3
Dimensions d = new Dimensions()
{
  Length = 2m;
  Width = 1m;
}

Originally, object initializers weren't able to initialize read only properties. Your object's properties would need a public setter. This feature was later added in C# 9.0 with the init keyword

// Since C# 9
public class Dimensions
{
  public decimal Length { get; init; }
  public decimal Width { get; init; }
}

Dimensions d = new Dimensions()
{
  Length = 2m,
  Width = 1m
}

d.Length = 3m; // compile error

If you use a manual backing field instead of an auto property, the init keyword permits a code block allowing us to enforce constraints here. Unfortunately we are limited to throwing an exception, just as we were using a constructor.

public class Dimensions
{
  private decimal _length;
  public decimal Length
  {
    get => _length;
    init
    {
      if (value <= 0) throw new ArgumentException("Must have positive length.")
      _length = value;
    }
  }
  public decimal Width { get; init; }
}

Dimensions d = new Dimensions()
{
  Length = 0m // runtime exception
}

In the previous example. The initializer didn't include a value for the width property. This would compile just fine, and it wasn't until C# 11 that we finally had a way to require properties as part of object initializers with the required keyword

// Since C# 11
public class Dimensions
{
  public required decimal Length { get; init; }
  public required decimal Width { get; init; }

  Dimensions d = new Dimensions()
  {
    Length = 2m
  } // compile error
}

Despite all these new language features, object initializers still retain the same issue as constructors and offer, near as I can tell, no tangible benefits. With the required keyword, and init block, object initializers and constructors seem to amount to an aesthetic difference. This is not the case with our last method of instantiation, which has been in the language from the very beginning.

Factories

Sorry to disappoint the Enterprise™ Developers, I do not mean the GoF Abstract Factory pattern. I am referring to a static function which has access to a private constructor for a type. Here is the trivial (useless) example:

public class Dimensions
{
  public decimal Length { get; }
  public decimal Width { get; }

  private Dimensions(decimal length, decimal width)
  {
    Length = length;
    Width = width;
  }

  public static Dimensions Create(decimal length, decimal width)
  {
    return new Dimensions(length, width);
  }
}

In this case, we've no advantage over a simple constructor or initializer, but our static method can choose it's return type. This enables much more robust error handling for constraint violations. Beyond simply returning null, here is an idiomatic TryParse implementation which allows Roslyn's branch analysis to know when you've got an instance of Dimensions and not null.

public class Dimensions
{
  public decimal Length { get; }
  public decimal Width { get; }

  private Dimensions(decimal length, decimal width)
  {
    Length = length;
    Width = width;
  }

  public static bool TryParse(
    decimal Length
    decimal Width
    [NotNullWhen(true)]
    out Dimensions? dimensions)
  {
    dimensions = null;
    if (Length <= 0 || Width <= 0) return false;

    dimensions = new Dimensions(length, width);
    return true;
  }
}

Because these factories are just functions, they can implement whatever method of error handling you prefer. Here's an example with a passed in error handler.

public static Dimensions? Create(
  decimal length,
  decimal width,
  Action<string> error)
{
  bool hasErrors = false;

  if (length <= 0)
  {
    error("Must have positive length.");
    hasErrors = true;
  }

  if (width <= 0)
  {
    error("Must have positive width.");
    hasErrors = true;
  }

  if (hasErrors) return null;

  return new Dimensions(length, width);
}

Here's an example using a result type.

public static Result<Dimensions> Create(decimal length, decimal width)
{
  List<string> errors = new();

  if (length <= 0) errors.Add("Must have positive length.");

  if (width <= 0) errors.Add("Must have positive width.");

  return errors switch
  {
    [] => new Dimensions(length, width),
    [message] => new Error(message),
    _ => new AggregateError(errors)
  };
}

Conclusion

As we can see the static factory functions provide us much more control around around error handling, and for this reason I tend to use static factory functions if I have any constraints at all.

The Argument

Why should we prefix the names of interfaces with I in C#? Here is the full answer given from Microsoft's documentation on C# coding standards. To save you the click, I'll post it here.

When naming an interface, use pascal casing in addition to prefixing the name with an I. This clearly indicates to consumers that it's an interface.

So we need to prefix the name of the type with I so that consumers of the type know that it's an interface. Seems simple and straightforward, but already this rule fails the consistency test. I could not find any suggestions that we preface class names with C and structs with S and records with R in order to indicate these things to consumers.

So the question then is, Why do consumers need to know they are using an interface, and why do consumers not need to know they are using a struct, class, or record?

Do Consumers need to know they are using an interface?

As far as I can tell you will encounter an interface in one of exactly three places:

1. You are defining the interface

2. You are implementing the interface

3. You are working with a variable that is of an interface type

Let's examine, in each of these three scenarios, how helpful it is to know that you are working with an interface, and how valuable that information is.

Defining an interface

public interface Entity
{
  string Id { get; set; }
}

Is it clear when defining this type, that it's an interface? Hopefully the word interface preceding the type name is sufficient to communicate that information to us.

Implementing an interface

public class Book : Entity
{
}

Is it clear when implementing the Entity type that it is an interface? Not Just by looking at it. In fact, we won't notice anything at all until we've run the compiler. Once we've run the compiler we will be informed that we've failed to correctly implement the interface.

But how soon after we type this code is a compilation or language service run? In many IDEs very shortly. The editors that I'm familiar with will not only alert me that I need to do something, they will provide a macro or tool tip to do it quickly (ctrl+. in visual studio).

In fact, whether or not Entity is an interface, or an abstract base class my process is the same. Wait for the red squiggles to appear and then using the auto-complete features to stub out the abstract members I need to implement.

So in this way, In the case that your editor settings don't provide color indicators for the information, You don't actually need to know whether or not you've implemented an interface or extended an abstract base class. The compiler knows there are things you have to add to your type definition.

"But Wait!" you say, "What about multiple inheritance?"

Ah yes, well any given type in C# can have any number of interfaces, but only one base type. Without the I how will we know which one is the base type and which one is the interface?

The answer is again, the compiler. If you're using a modern editor you will likely know very quickly if you've extended multiple base classes, whether by color coding, or language features running error checking as you type. In this case, I don't need an I in front of my interface name any more than I need an A in front of abstract class names.

Working with a variable of an interface type

What if you get a variable back from a function, and the type is Entity and you aren't sure whether that type is an interface or a concrete type?

Even if you are not using an editor that can quickly communicate that information, I would argue that it makes no difference. You don't care if that type is an interface. You care what that type tells you about what methods are on it, and what methods it can be passed into as a parameter. That information is not only quickly available to you in most modern editors, but it's also impossible to determine any of it by whether or not there is an I at the beginning of it's name.

Following the convention

Okay, so maybe it's actually not that helpful, but is there any value in following the convention? There very well could be, but that's not the whole question. The question is: "at what cost?"

If Naming things is hard, Why make it harder? We either end up adding I's to everything or you have long descriptive names using I to describe what an object can do, i.e. ISaveBooks

Sometimes it's common to use the I to distinguish The interface from The implementation. These types often come in pairs: IBookRepository, BookRepository. The idea here being that we can code against the interface, not the concrete type. There are many good reasons to do this, and nearly all of them go away if our interface has only one implementation. In such a case, the ceremony is all noise and no signal. The interface defines what the type can do, but the name of the implementation doesn't communicate anything to us. What would be useful to see is a descriptive name of how, such as SqlBookRepository, or InMemoryBookRepository. In this, far more clear, example we no longer need to preface our interface with I. The interface is BookRepository and we have two implementations, one that reads and writes books from a SQL database, and one that keeps them in memory. For this problem, I much more likely to do something like this:

public interface BookWriter
{
  Task Save(Book book)
}

public interface BookReader
{
  Task<Book> Load(string bookId)
}

public class SqlBookRepository : BookWriter, BookReader { ... }
public class InMemoryBookRepository : BookWriter, BookReader { ... }

Aside from the clarity, I no longer need to force a service which only reads books to be bound to the functionality around saving them. If I have any other functionality I might want to insert using decorators, like publishing an event every time a book is created or updated, I can do so without needing to write an empty pass through on the read part of the repository.

For me, I've not found any argument to prefix my interface names with I any more compelling than the idea that I should prefix my class names with C. It's an old convention, a relic of Hungarian notation, something which even other parts of the recommended C# coding conventions have gone away from.