DEV Community: Sam Ferree

The Trouble with .Single()

Sam Ferree — Wed, 03 Jan 2024 13:49:19 +0000

*in this article I will use list to refer to any enumerable collection not just List<T>

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 class 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 vs Initializers vs Factories

Sam Ferree — Thu, 14 Dec 2023 09:46:17 +0000

In C# it can be quite useful to obtain an instance of an object. What is important to us as designers of types, are the different ways we can permit others to do this.

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.

View this post and more like it at my blog

No Sacred Cows: I, Interface

Sam Ferree — Wed, 16 Feb 2022 21:22:03 +0000

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:

You are defining the interface
You are implementing the interface
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.

Find this article and more on my substack

Maybe, but How?

Sam Ferree — Tue, 25 Jan 2022 15:41:11 +0000

Null considered harmful

The problem with null has been discussed at length. With the newer versions of C# the compiler is capable of helping us keep track of reference variables, which may or may not be null, but it isn't bulletproof. This is a problem that other languages have never had, so how do they deal with the possibility that some data isn't present?

In dynamic languages like JavaScript, sometimes the idea is punted entirely, and not only can null be found, but undefined as well. In statically typed languages like Haskell and F#, they use generic Maybe (Option in F#) types. Can we have these types in C#? How would we implement and use them?

A List of 0 or 1

One way to think of a Maybe type is to think of it as a list, which will either have 1 item of the generic type, or 0. Implemented this way, it can be worked with like any other IEnumerable in C#.

public class Maybe<Item> : IEnumerable<Item>
{
  private readonly Item[] _array;
  public Maybe(Item item)
  {
    if (item is null) _array = new Item[0];
    else _array = new Item[] { item };
  }

  public Maybe() => _array = new Item[0];

  public IEnumerator<Item> GetEnumerator() => _array.GetEnumerator();
  public IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
}

This implementation takes advantage of the fact that lists can always be used in a null safe way, since an empty list is a valid list. Anyone familiar with LINQ will be able work with such an implementation. What this implementation lacks is intent. There's nothing about it's external API which indicates that there will either be 0 or 1 items. You can also get right back to null with a call to SingleOrDefault, or throw an exception if you call Single. Note too that functional LINQ calls like Select and Where will return an IEnumerable<Item>, not another Maybe<Item> without implementing those methods specifically.

An Abstract Type, with Private Concrete Types

public abstract class Maybe<Item>
{
  abstract Output Match<Output>(
    Func<Item, Output> Some,
    Func<Output> None);

  public static implicit operator Maybe<Item>(Item value) => new Some(value);
  public static Maybe<Item> Not() => new No<Item>();

  private class Some<Item> : Maybe<Item>
  {
    private Item Value { get; }
    public Some(Item value) => Value = value;

    public override Output Match<Output>(
      Func<Item, Output> Some,
      Func<Output> None) => Some(Value);
  }

  private class No<Item> : Maybe<Item>
  {
    public override Output Match<Output>(
      Func<Item, Output> Some,
      Func<Output> None) => None();
  }
}

This implementation hides the underlying mechanisms and exposes only a single API for working with a Maybe type: Match. The goal of Match is to obtain a new value by providing code to handle both when a value exists, and when a value does not. Consider the following equivalent code:

string message;
SomeType? oldSchool = null;
if (oldSchool is not null) message = $"Variable was not null: {oldSchool}";
else message = "Variable was null";

Maybe<SomeType> newSchool = Maybe<SomeType>.Not();
message = newSchoole.Match(
  Some: instance => $"Variable was not null: {instance}",
  None: () => "Variable was null");

This provides some helpful constraints to the programmer, as both cases must be handled or the code won't compile. However there's no way to use the presence of a value to do some work that has no return, at least not without borrowing other concepts from functional languages like a Unit value. More functional abstract methods are possible, like mapping and flattening (Select and SelectMany in LINQ lingo.)

An Abstract Type, with Public Concrete Types

This is the implementation I use. It allows us to use familiar C# pattern matching, and provides plenty of avenues for functional extension methods as needed.

public abstract class Maybe<T>
{
  static Maybe() {
    Some<T>.SetFactory();
  }

  internal static Func<T, Some<T>> newSome = null!;

  public static implicit operator Maybe<T> (T? value) => value is null ? No<T>.Value : newSome(value);
}

public class Some<T> : Maybe<T>
{
  public T Value { get; }
  private Some(T value) => Value = value;

  public static implicit operator T(Some<T> some) => some.Value;

  internal static Unit SetFactory()
  {
    newSome = value => new Some<T>(value);
    return Unit.Value;
  }
}

public class No<T> : Maybe<T>
{
  private No() { }
  public static Maybe<T> Value => new No<T>();
}

This implementation allows the client code to observe and work with Some<Item> and No<Item> types, but hides their constructors leaving only the implicit conversion and No<Item>.Value as the way to obtain them as Maybes.

We can use C#'s built in pattern matching to provide an API that feels much more idiomatic, like the following code:

Maybe<User> maybeUser = GetUser(id);
if (maybeUser is Some<User> someUser)
{
  DoThingWith(someUser.Value);
}
else
{
  ReportMissingUser(id);
}

string message = maybeUser switch
{
    Some<User> someUser => someUser.Value.Greeting(),
    No<User> => "User Not Found",
    _ => throw new BadMaybe(maybeUser); // Implementation not shown.
}

Conclusion

There are several ways to implement a maybe type in C#, each with their own pros and cons, but all of them are more expressive, and more type safe that relying on null checking.

Find this article and more on my substack

Explicit Registration in ASP.NET Core DI

Sam Ferree — Mon, 10 Aug 2020 17:21:22 +0000

Sometimes you'll want a little more control over how your objects are composed than the IServiceCollection API gives you. You can always fall back to explicit registration.

The AddTransient/Scoped/Singleton methods all have an overload that takes a Func as a factory method to use when an instance is needed.

When is this useful? let's say you have the following objects

public interface IPing
{
  void Ping(string msg);
}

public class ConsolePing : IPing
{
  public void Ping(string msg) =>
    Console.WriteLine(msg);
}

public class LogPing : IPing
{
  public void Ping(string msg) =>
    Log.Info(msg);
}

So you have to different implementations of IPing, then for different services you wanted to inject different implementations, but still only take a dependency on the interface for test mocking.

public class ServiceA
{
  private readonly IPing _pinger;
  public ServiceA(IPing pinger) => _pinger = pinger;
}

public class ServiceB
{
  private readonly IPing _pinger;
  public ServiceB(IPing pinger) => _pinger = pinger;
}

How do you register ServiceA and ServiceB so that A gets the ConsolePinger, and B gets the LogPinger? Use the overload registration that takes in a factory method.

The factory method needs to return an instance of the service you are registering, but it takes as a parameter a service provider that can be used to obtain any dependencies.

public void ConfigureService(IServiceCollection services)
{
  services.AddTransient<ConsolePing>();
  services.AddTransient<LogPing>();
  services.AddTransient<ServiceA>(provider =>
  {
    var consolePinger = provider.GetRequiredService<ConsolePing>();
    return new ServiceA(consolePinger);
  });

  // if you can also omit the generic parameter
  services.AddTransient(provider =>
  {
    var logPinger = provider.GetRequiredService<LogPing>();
    return new ServiceB(logPinger);
  });
}

Into the Unknown - Working with Missing Data in C# Part 1: Being Explicit

Sam Ferree — Fri, 12 Jun 2020 17:40:32 +0000

Prerequisites

This post assumes you have some knowledge of C-style object oriented languages, ideally C#, as well as Generics.

The Problem.

public int Length(string str)
{
  return str.Length;
}

This has a pretty nasty bug it's hiding. (Ignore the redundancy of it for now...) This function claims to take a string, and return length of it.

But that's not the whole truth, Unless you're working in C# 8+ (with the nullable switch enabled) you can pass this function a value that isn't a string, or anything actually

int length = Length(null)

And even if you are working in C# 8+ with the Nullable flag enabled, the compiler would only give you a warning, which can be suppressed with the ! operator

Now, in C# you can throw a slightly more helpful error

public int Length(string str)
{
  if (str is null)
    throw new ArgumentNullException(nameof(str));

  return str.Length;
}

This will let the caller know which parameter wasn't allowed to be null, and of course C# 8 will give you a little warning at compile time. Note that this warning doesn't actually prevent null from being passed in. It just gently pokes you at compile time that something may be brewing.

Now the C# 8 feature I've been referring to is called Nullable Reference types, and it's a way to be more explicit about types which may be null. If for instance, I had wanted to express that this function could handle a null value, I could have written it this way:

public int Length(string? str)
{
  if (str is null)
    return 0;

  return str.Length;
}

This would let the caller know that the Length function accepts null. This is a great feature that makes null reference errors less likely to pop up, but doesn't really offer the kind of bullet proof compiler safety i'd like out of a strongly typed language.

The Goal

What we're looking for is not just a way to inform fellow coders that some information could just plain be missing, but to have the compiler force them to deal with that possibility. It's the not handling of the null case that causes errors, and the compiler's in ability to actually force the coder to deal with it that causes them at runtime.

But this problem is actually solved, just not in C#. At least not in the language itself.

Let's look at arguably the strongest typed language, Haskell. Here's how I would define a list of numbers, that could possibly have no value (not even an empty list). You don't commonly have to specify the types in haskell, but here it is anyway

Num t => Maybe [t]

This basically tells haskell that we might have a list of objects which fall into the Num typeclass.

So how do you work with a Maybe? The most trivial thing you can do is match on it. If you're trying to get the count of negative numbers from a list which might be Nothing, the Haskell compiler will force you to provide instructions for what to do in that case.

Can we do this in C#? As is turns out we can, and a number of ways.

A Solution

I'll define just one way of implementing the Maybe type here. To fit in with the wider .NET Ecosystem, I'll call it an Option to match F#'s built in type for this. From here on out I will refer to our custom "Maybe" type as an "Option" type

public struct None { }
public static class Option 
{
  public static None None { get; } = new None();
}

public struct Option<T>
{
  public static implicit operator Option<T>(None none) => new Option<T>();
  public static implicit operator Option<T>(T value) => new Option<T>(value);

  private readonly bool _hasValue;
  private readonly T _value;

  private Option(T value)
  {
    _hasValue = value is { }; // 'is not null' is planned for C# 9.0
    _value = value;
  }
}

Some things to note here, The None and static Option types are helpers, they are going to make this more readable when we actually use it. The constructor of the option type is private. Since it is a struct, there is still a parameter less constructor available, but the struct type will prevent anyone from assigning an Option the value of null, which is what we're trying to avoid in the first place. The preferred way to instantiate an option type is to use one of the implicit conversions. You can either convert an instance of None, or an instance of T. Note too that the constructor which takes in an instance of T will check if it's null, and if it is, will behave as though it was converted from an instance of None. This prevents a programmer mistake from trying to "Force" a null into option by typing something like Option<string> s = (string)null;

Now as it stands, this option type is like a sealed box. And the value may or may not be in that box, so how do you get the value out of the box. There's a pretty good argument to say that shouldn't actually try to do that, and I'll cover more about what that means and how that works in a later post, but for now let's give ourselves a way to get the value out of the Option type, by forcing us to provide something to do in the case that it is missing entirely.

Let's add the following class method to the Option type.

public TOut Match<TOut>(Func<T, TOut> Some, TOut None) =>
  _hasValue ? Some(_value) : None;

This method takes two parameters, first, a Function from T to TOut which will be executed if the option contains a value, and a TOut value will be returned if the option does not contain a value. So if we wanted to use this to calculate the length of a string which we only might have, it could look something like this.

public int Length(Option<string> strOption)
{
  return strOption.Match(
    Some: str => str.Length,
    None: 0);
}

Here I am using named parameters to make it a little more clear, but we're matching Some string to string.Length, and None to 0. C# can infer the generic TOut parameter as int, so it also helps us out a little.

Here's now some of the values our Option accepting function can safely handle

Length("hello"); // string get's implicitly converted to Option<string>
Length(Option.None) // Also implicitly converted
Length(null); // warning thrown by the C# 8 compiler. In this case, will convert null to string, and be caught by converter.
Length(null!); // as above but compiler warning is suppressed.

Next time, we'll circle back to where I mentioned that in most cases you don't actually want to "Get the value out the box" and what would be better to do instead.

How to avoid mocking repository for Unit Tests

Sam Ferree — Fri, 12 Jun 2020 12:47:10 +0000

I commonly see code written like this, even in courses.

public class DeskBookingProcessor
{
  public readonly IBookingRepository _bookingRepository;
  public readonly int _capacity;

  public async Task<Booking?> Book(BookingRequest request)
  {
    var currentBookings = await _bookRepository.GetBookingsAsync(request.Date);
    if (currentBookings + 1 > _capacity)
    {
      return null;
    }
    else
    {
      var booking = new Booking(request);
      await _bookingRepository.SaveAsync(booking);
      return booking;
    }
  }
}

The drawback is you have to mock a whole IBookingRepository (Even the methods this feature doesn't use) to test your booking logic.

Alternatively, you could do this

public class BookingAgent
{
  public Booking? Book(BookingRequest request, int currentBookings, int capacity) =>
    currentBookings + 1 > capacity
      ? null
      : new Booking(request);
}
public class DeskBookingProcessor
{
  public readonly IBookingRepository _bookingRepository;
  public readonly int _capacity;

  public async Task<Booking?> Book(BookingRequest request)
  {
    // Impure Collect
    var currentBookings = await _bookRepository.GetBookingsAsync(request.Date);
    var agent = new BookingAgent();

    // Pure Calculation
    var booking = agent.Book(request, currentBookings.Count(), capacity);

    // Impure Commit
    if (booking != null) await _bookRepository.SaveBookingAsync(booking);

    return booking;
  }
}

Now your unit tests don't need to mock impure dependencies, just test the BookingAgent by passing the parameters.

Leave it to your integration tests flex the combination of the pure logic and impure dependencies. Prefer the kind that stand up a whole test server and send HTTP requests and check HTTP responses.

That is all.

Avoiding Exceptions in ASP.NET Core

Sam Ferree — Mon, 13 Aug 2018 12:04:59 +0000

Prerequisites

To get the most out of this post, it's best if you are familiar with Object Oriented Programming, C# (or other C family language) and the basics of ASP.NET Core and MVC architecture.

If you're unfamiliar with any of these topics, but want to learn more here are some fantastic pluralsight courses:

If you don't have a pluralsight membership, they offer a 10-day free trial. If you want my two-cents: I've tried Treehouse, Udemy and others and Pluralsight is my clear winnner. Whether you're a code newbie or a seasoned engineer it's well worth the monthly fee.

Why I dislike dealing with exceptions

Throwing Exceptions is Dishonest

Consider the following code snippet:

public decimal SquareRootOf(int x)
{
    if(x < 0)
        throw new ArgumentException("x is negative");

    // Calculate the square root
}

We see code like this all the time, and it's not a terrible practice. It's a good defensive programming practice to validate data that is passed into functions. But this function lied. It said it was going to return a decimal when passed an int, and it might, but it might also return an ArgumentException. There are a couple ways this code might be made more honest, but one appropriate fix is to be more honest about what type of parameters you can accept. If this function was declared that x was of type uint, then no check is needed and it can honestly say that yes, uint's always get decimals's back.

Exception Handling is a Poor Way to Control the Flow of Execution

Consider the following controller action for ASP.NET Core

[HttpDelete("{id}"]
public IActionResult DeletePost(int id)
{
    try
    {
        var post = _postRepository.GetPostById(id);

        var currentUser = _userService.GetCurrentUser();

        if(post.Author.Id == currentUser.Id)
        {
            _postRepository.Delete(post);
            return NoContent();
        }

        return Forbid();
    }
    catch (NotFoundException nfe)
    {
        return NotFound();
    }
    catch (AuthorizationException ae)
    {
        return Unauthorized();
    }
    catch
    {
        return StatusCodeResult(500);
    }
}

Sure looks like resilient code. It checks for authorizations, returns custom exceptions that map nicely to the appropriate HTTP result. But it looks a bit jarring, and the control flow is routed mostly by exceptions. Additionally, we have some validation logic in here, and I prefer to keep the single responsibility of my controllers confined to orchestration.

Life Without Exception Handling

This is not a post about railway programming.

Imagine, if objects honestly told you they could return a few different types? What if a repository method could tell you "I'm going to return either a Post or an Exception"? Wouldn't that be nice.

Well there is a concept borrowed from functional programming, call railway oriented programming that is just that... but I won't be talking about it here. Personally, I've walked down this road before, and once you correctly deal with Asynchronous controllers... the readability (IMHO) just vanishes, and I suspect that C#, while multi-purpose, just isn't quite there yet to support paradigms so closely tied to functional programming. I prefer a more Object oriented approach. I will however leave this link for the interested.

Railway Oriented Programming

Note: This post details railway oriented programming in F#, a proper functional language that is much more suited to this task than C#, but it explains the concept. For information on how it's done in C#, Zoran Horvat has this great course (yes, on pluralsight) about making your C# code more functional, and it has a module on railway oriented programming.

An old favorite, the Result class

I really have only one question when I ask some service method to do something, or get me something. Did it work? IF so, I've got the thing, and I can move on. IF something when wrong, I should be able to fail fast and return whatever error occurred further up the chain (As we are used to doing with exceptions)

There's an old pattern that I've used in many languages and frameworks, where a wrapper class holds both the data, and the success/failure information of the call.

Since we're confining ourself to the domain of ASP.NET Core controllers, we get a big break. Something that works can return the object we wanted. Something that fails can return an ActionResult. Since the class doing the actual work knows more about exactly what went wrong than the controller, it can return the correct ActionResult. This way, the controller is now relieved of the job of mapping exceptions to status codes, and can focus entirely on it's single responsibility of orchestration.

Let's look at some code, first a result implementation for void methods

public abstract class Result
{
    public ActionResult ErrorResult { get; private set; }

    public bool Errored => ErrorResult != null;

    protected Result()
    {
        ErrorResult = null;
    }

    protected Result(ActionResult errorResult)
    {
        ErrorResult = errorResult;
    }

    private class Success : Result { }

    private class Error : Result
    {
        public Error(ActionResult errorResult) : base(errorResult) { }
    }

    public static Result WithoutError => new Success();

    public static implicit operator Result(ActionResult errorResult) => new Error(errorResult);
}

Let's unpack this a bit here.

First, I like making result class abstract because I don't want people using the constructor. There's a static factory property, and an implicit conversion we'll talk about later.

The one field of the Result is the ActionResult ErrorResult. Since ActionResult implements IActionResult and ASP.NET Core controllers usually return IActionResult, we can take any Result that Errored, and just return it's ErrorResult property.

Then I define two private implementations of Result: Success and Error. I don't want any users to actually know about these types, they are just implementations for me to use when I need to instantiate a Result object

Next we have a way to indicate the successful run of a void method a static property that returns a new instance of Success, encapsulated behind the Result type.

Then we have an implicit conversion from any ActionResult to a Result that instantiates a new Error (again, encapsulated)

So then we can return from "void" methods the following way


public Result DoSomething()
{
    // Do Something
    return Result.WithoutError;
}

public Result DoSomethingThatFails()
{
    // Do Something That Fails
    return new InternalServerError();
}

public Result DoSomethingThatWorks()
{
    // Do Some Stuff

    Result otherMethodResult = Other.MethodThatWorks();

    // Fail Fast
    if(otherMethodResult.Errored)
        return otherMethodResult.ErrorResult;

    // Do Some More Stuff

    return Result.WithoutError;
}

So we see how to return without error, return ActionResult objects and have them converted to Result by the compiler, and easily return errors from other Result types. Works well for commands, but this doesn't give us data back from queries.

Getting something back, with Result

So what about methods that were supposed to return me some data? How do I get it? Well, we have another subclass of Result that can handle this

public class Result<T> : Result
{
    public T Value { get; private set; }

    private Result(T value)
    {
        Value = value;
    }

    private Result(ActionResult errorResult)
        : base(errorResult) { }

    public static implicit operator Result<T>(T value) => new Result<T>(value);
    public static implicit operator Result<T>(ActionResult errorResult) =>
        new Result<T>(errorResult);
}

So now I've added a field for the data we hope to return, and made the class generic so we can make results of any type. I've kept the constructors private because I want people to use the implicit conversions. So methods that return Result can either return the object of type T, or any ActionResult that represents an error.

Side Note: Yes, you can make an object with a method that returns a Result<ActionResult>... or in other words always returns some ActionResult, for both successes and errors, which seems a little confusing... And it certainly would not play nice with the constructors and implicit conversions we've set up... but there is already an abstraction for objects that always return an HTTP results whether the action was a success or not. They're called controllers! It probably doesn't make sense for a controller to be making queries to some object that is essentially another controller... so I think returning Result<ActionResult> is a pretty pungent code smell. Moving on...

Let's revisit our delete post action, where we can see that the controller has reduced it's responsibility to nothing more than orchestrating the process for resolving a request, and it fails fast as soon as some part of that process returns an error.

[HttpDelete("{id}")]
public IActionResult DeletePost(int id)
{
    Result<User> getUser = _userService.GetCurrentUser();

    // The user might be unauthenticated, the user
    // service is now responsible for detecting that
    // logging it, responding with challenge etc.
    if (getUser.Errored)
        return getUser.ErrorResult

    Result deletion = _postRepository.DeletePost(id, getUser.Value);

    // Was the post not found? 
    // Was the user unauthorized?
    // Did we lose our database connection? 
    // We don't know, we don't care. 
    if(deletion.Errored)
        return deletion.ErrorResult;

    // All must have went well.
    return NoContent();
}

Whew! This was a long post, and thanks for making it all the way to the end! If you have any questions or comments, feel free to leave them here, or if they come to you later, tweet them may way @sam_ferree! Like the idea? Fork me on GitHub

Using the Strategy Pattern (Examples in C#)

Sam Ferree — Tue, 15 May 2018 18:50:55 +0000

Prerequisites

To get the most out of this post, it helps if you have a basic understanding of object oriented programming and inheritance, and an object oriented programming language like C# or Java. Although I hope you can get the main idea behind the strategy pattern even if you aren't an expert in C# syntax.

Example Problem

We're working on an application that keeps files in sync, and the initial requirements state that if a file exists in the destination directory but it doesn't exist in the source directory, then that file should be deleted. We might write something like this


public void Sync(Directory source, Directory destination)
{
    CopyFiles(source, destination)
    CleanupFiles(source, destination)
}

private void CleanupFiles(Directory source, Directory destination)
{
    foreach(var destinationSubDirectory in destination.SubDirectories)
    {
        var sourceSubDirectory = source.GetEquivalent(destinationSubDirectory);
        if(sourceSubDirectory != null)
        {
            CleanupFiles(sourceSubDirectory, destinationSubDirectory);
        }
        else
        {
            // The source sub directory doesn't exist
            // So we delete the destination sub directory
            destinationSubDirectory.Delete();
        }
    }

    // Delete top level files in this directory
    foreach(var file in destination.Files)
    {
        if(source.Contains(file) == false)
        {
            file.Delete();
        }
    }
}

Hey they looks pretty good! We used recursion, and it's all pretty readable. But then, as with all software projects, the requirements change. We find out that sometimes, we don't want to delete extra files. That's an awfully quick fix. We can do that by checking a flag.

public void Sync(Directory source, Directory destination)
{
    CopyFiles(source, destination)
    if(_shouldDeleteExtraFiles)
    {
        CleanupFiles(source, destination)
    }
}

Because we separated the delete logic into it's own method, a simple If statement gets the job done. Until the requirements change again. Now we want the app to give the user the option to keep files that have the .usf extension. This requires us to make a change in our CleanupFiles method.

private void CleanupFiles(Directory source, Directory destination)
{
    foreach(var DestinationSubDirectory in destination.SubDirectories)
    {
        var sourceSubDirectory = source.GetEquivalent(DestinationSubDirectory);
        if(sourceSubDirectory != null)
        {
            CleanupFiles(sourceSubDirectory, DestinationSubDirectory);
        }
        else
        {
            // The source sub directory doesn't exist
            // So we delete the destination sub directory
            destinationSubDirectory.Delete();
        }
    }

    // Delete top level files in this directory
    foreach(var file in destination.Files)
    {
        if(_keepUSF && file.HasExtension("usf"))
        {
            continue;
        }

        if(source.Contains(file) == false)
        { 
            file.Delete();
        }
    }
}

Hmm, now we've added a couple of global flags, and we have the logic that depends on them spread across multiple methods. (Outside the scope of this post, we might also need to check that destination directories that don't exist in source contain files with the .usf extension.) We could really benefit from cleaning this code up. How should we separate our logic out so that the decision making about which delete logic to use, and the logic itself aren't so intertwined?

Enter the Strategy Pattern.

From w3sDesign.com:

the strategy pattern (also known as the policy pattern) is a behavioral software design pattern that enables selecting an algorithm at runtime. Instead of implementing a single algorithm directly, code receives run-time instructions as to which in a family of algorithms to use.

Now I know I've been talking about the need to clean this code up, not select an algorithm at runtime. We already have the ability to change the algorithm at runtime, because of our use of flags, but we will see the benefits of cleanup.

First, let's code to an interface.

public interface IDeleteStrategy
{
    void DeleteExtraFiles(Directory source, Directory Destination);
}

To simplify, let's say the client will pass this into our method, so we update it's signature and content like so:

public void Sync(
    Directory source,
    Directory destination,
    IDeleteStrategy deleteStrategy) //Expect to recieve a delete strategy
{
    CopyFiles(source, destination)

    //Call our delete strategy and let it handle the clean up
    deleteStrategy.DeleteExtraFiles(source, destination)
}

Well, that certainly cleans up things. Now let's look at some implementations. First the trivial option, don't delete anything. If this strategy is passed in, the method call will do nothing, and any extra files in the destination directory will remain.

public class NoDelete : IDeleteStrategy
{
    public void DeleteExtraFiles(Directory source, Directory Destination)
    {
        //Do nothing!
    }
}

Now, we could write two distinct strategies for deleting files that are not in source, and keeping USF files, but the policy for keeping USF files is an extension of the policy to delete files that are not in the source. So we can save some code here with inheritance.

Here is our strategy to delete files in the destination directory if they're not in the source directory. Note that we've kept the recursion from before to clean up sub-directories, but we've broken out the logic for deleting top level files, and deciding whether or not we should delete a file.

public class DeleteIfNotInSource : IDeleteStrategy
{
    public void DeleteExtraFiles(Directory source, Directory Destination)
    {
        foreach(var destinationSubDirectory in destination.SubDirectories)
        {
            var sourceSubDirectory = source.GetEquivalent(destinationSubDirectory);
            if(sourceSubDirectory != null)
            {
                // use recursion to pick up sub directories
                DeleteExtraFiles(sourceSubDirectory, destinationSubDirectory);
            }
            else
            {
                // The source sub directory doesn't exist
                // So we delete the destination sub directory
                destinationSubDirectory.Delete();
            }
        }

        DeleteTopLevelFiles(source, destination);
    }

    private void DeleteTopLevelFiles(Directory source, Directory destination)
    {
        foreach(var file in destination.Files)
        {
            if(ShouldDelete(file, source))
            { 
                file.Delete();
            }
        }
    }

    protected bool ShouldDelete(File file, Directory source)
    {
        return source.Contains(file) == false;
    }
}

So now we actually just need to implement our strategy to Keep usf files by inheriting from DeleteIfNotInSource and overriding the ShouldDelete method!

public class KeepUSF : DeleteIfNotInSource
{
    public override bool ShouldDelete(File file, Directory source)
    {
        if(file.HasExtension("usf"))
        {
            return false;
        }

        //Defer to our base class
        return base.ShouldDelete(file, source);
    }
}

So now if we needed to add a new strategy, we wouldn't have to touch any of our other code. We could create a new class that implements the IDeleteStrategy interface, and just add the logic for selecting it.

For instance, we can use something like configuration settings to select a strategy, then pass it into our sync method. Here's an example of what that might look like (using the Factory pattern, if you're looking for further reading)

// The application configuration tells us what delete strategy we are using
var deleteStrategyFactory = DeleteStrategyFactory.CreateFactory(configSettings);
...

// We don't know exactly what strategy we're getting, 
// better yet we don't care!
var deleteStrategy = deleteStrategyFactory.getDeleteStrategy();
SyncProcess.Sync(source, destination, deleteStrategy);

Pumping the Brakes.

Some of you familiar with design patterns might be saying "Hey Sam, why didn't you implement the Keep USF functionality with the Decorator pattern!?" (More further reading if you're up for it.)

Sometimes, it's best not to apply a design pattern just because you can. In fact, this example was kept simple for educational purposes. An argument could have been made that the Strategy pattern here is overkill.

Make sure you weigh the gains from applying a design pattern against the cost of applying it. Applying the strategy pattern here added an interface, and three new classes to our project. In other words: "Make sure the juice is worth the squeeze."

Why (I think) "Cost of Living" pay for remote workers is BS.

Sam Ferree — Wed, 09 May 2018 14:04:30 +0000

1. The Fundamental Message Is Terrible.

I'm not going to build up here and just go with what I think is the biggest concern. When a company adjusts pay based on a remote employee's location, what they explicitly saying is that "Your compensation is not based solely on the value you bring to the company." Think about that for a second. Two employees who generate the same value for the company, are paid different rates, simple because of where they are.

"But wait Sam! They just want employees to have the same quality of life!" Well...

2. The "Quality of Life" Argument is also BS.

You can't enforce an equal quality of life by scaling pay, because cost of living is a function of quality of life. Places like San Francisco and Miami are more expensive because demand is higher. Demand is higher because people think they are better places to live.

Does anyone honestly think that a studio apartment in Palo Alto is the same quality of life as a studio apartment in Sheldon, Iowa? There are so many factors at work here they go beyond living space (cost of rent is one of the most popular inputs to cost of living pay calculators). That apartment in the bay area has great weather, it's above a fun little Thai fusion dive bar, and within walking (or public transport) distance to some of the worlds largest tech conferences and meetups. Meanwhile, an employee in Iowa has to drive an hour for a P.F. Chang's and has to wake up 5am to shovel his driveway 5 months out of the year to get his kid to school. That's why he gets four bedrooms and a boat (which again, he can only use half of the year).

3. It's Legally Dangerous.

Diversity and inclusion are one of the top (if not THE top) priorities for many tech companies and rightly so. It goes without saying that none of these companies would ever dream of scaling pay based on race. But it's well understood that zip code is a proxy for race. It wouldn't be hard for a civil rights attorney to overlay a map of racial distribution with a map of cost of living and see what lines up. This represents a HUGE HR risk.

Does any company really want to try explain to an employee that he makes less than his peer who happened to inherit a home in an affluent city from a grandparent that the pay difference isn't a consequence of privilege?

4. It's Game-able

Humans are smart. Post office boxes are real things. Many people live full time out of campers, or hop from AirBnB to AirBnB. Now it's HR responsibility to check up on employees constantly, "I see you have a lot of photos from Utah on your facebook... do you really live in Soma?"

5. It Goes Against The Essence of Remote Working, In The Most Greedy Way.

The entire point of remote work, or remote first companies (like GitLab, who scale pay based on cost of living.) is that where you are doesn't matter... Except it suddenly does when it can save the company some money. Note that many of these Silicon valley startups and tech giants have founders and C-level executives who just happen to live in these high cost of living places.

6. "It shouldn't just be about the money!"

It's been said by some that employees who are focused solely on the monetary compensation aren't a good fit, and they should care about the work they do and the people they work with and the company culture they're a part of.

All true, but that doesn't mean employees that like their job, colleagues, and company deserve to get paid any less than employees that are just in it for the money.

7. It can punish people who are already disadvantaged.

Consider two engineers at the same level in an organization, one a single male who lives in a small apartment in the center of a bustling metropolis. One, a recently divorced mother of two who finds her self unable to afford her downtown condo. She needs to move to a more affordable place and not just for housing, there's things like childcare to consider as well. She finds a small town with great schools and affordable housing, and what is the outcome of a cost of living "Fair to all employees" system? She gets a pay-cut on top of the all the new hardships she has to deal with.

The whole reason people move to lower cost of living areas is to make their money go farther, and this isn't always a personal choice, sometimes it's out of necessity.

8. These pay differences compound.

It's very easy to say "Rent costs twice as much in city B, so employees in City B make twice as much" and think that's even. But so many parts of a standard compensation package are based on this base salary. Bonus calculations are often a percentage of base salary. 401k or IRA contributions are a percentage of base salary. Raises (which compound annually) are almost always done by percentage.

This Week I Learned Vol 2.

Sam Ferree — Fri, 02 Mar 2018 14:08:02 +0000

Really enjoyed the responses I got last week, so I thought I'd go for round 2!

Share anything you learned, no need to be dev related.

This Week I Learned

Sam Ferree — Fri, 23 Feb 2018 18:29:17 +0000

Would love to see what cool things you guys learned. These can be ideas, tips and tricks, or anything really.

I'll start:

At a conference this morning, A talk on security mentioned monitoring the package dependencies people were adding to your project.

It's a great habit that I'd never even considered. We tend to give packages that our projects depend on a pass on security.