DEV Community: Maxime Gélinas

Never Return Null Again

Maxime Gélinas — Tue, 01 Dec 2020 16:41:22 +0000

null is probably the worst mistake in programming languages history and has spread in all modern languages since its
invention in 1965. Many years later, Tony Hoare, the inventor of the
null reference, even apologies for his mistake:

I call it my billion-dollar mistake. ... My goal was to ensure that all use of references should be absolutely safe,
with checking performed automatically by the compiler. But I couldn't resist the temptation to put in a null
reference, simply because it was so easy to implement. This has led to innumerable errors, vulnerabilities, and system
crashes, which have probably caused a billion dollars of pain and damage in the last forty years.

In this article, I will explain how null affect code integrity and how we can avoid using it and most importantly
returning it to improve code reliability.

What is wrong with `null`?

Well, let's give it a chance and see what happens. Imagine an e-commerce app allowing customers to get one discount each
month. Such a requirement could have been implemented like so:

public IDiscountCoupon GetMonthlyDiscountCoupon()
{
  // some changes...
  if (MonthlyDiscountAlreadyUsed()) return null;
  return new RandomDiscountCoupon();
}

Notice that if the monthly discount has already been used, null is returned.

From the implementation point of view, this is pretty obvious the result can either be a RandomDiscount or null, but
what about the usage point of view?

public void ApplyMonthlyDiscount(Order order)
{
  var coupon = GetMonthlyDiscountCoupon();
  // What now? How do I know if the next line will hit a null reference exception?
  // `coupon.ApplyDiscount(order);`
}

As you can see from the usage point of view, it is not that obvious. Of course, there is a chance you know null can be
returned, because you implemented both sides, you spent much time analyzing each used method or by some miracle, someone
decided to write documentation about it. Let's pretend it is the case for now so we can complete the above method:

public void ApplyMonthlyDiscount(Order order)
{
  var coupon = GetMonthlyDiscountCoupon();
  if (coupon == null) return;
  coupon.ApplyDiscount(order);
}

Great, now we handle null reference exceptions, that was easy! Well, think about what could have happened if the "one
coupon by month limit" requirement was introduced after the first attempt of ApplyMonthlyDiscount. In that case,
GetMonthlyDiscountCoupon could have looked like this:

public IDiscountCoupon GetMonthlyDiscountCoupon() => new RandomDiscountCoupon();

And so ApplyMonthlyDiscount could have never check for null references.

Does that means we should always check for null references based on the fact that methods can change and return null
in future?

No, as you can imagine this could quickly become a mess of null checks making the code lease readable and hard to
follow.

Establishing the rule

A better solution is to establish an important programming rule across your team. This rule is simple:

Never return null.

Of course, some verifications will have to be done to enforce this rule such as making it part of code reviews of
enabling some language features like the
nullable reference types in C# 8.0 or the
strictNullChecks flag in TypeScript.

Now that the rule is set, we can take it for granted and get rid of these annoying null checks!

Still, be aware that method arguments should still be validated. Values coming out can be controlled but values coming
in cannot. Take a look at guard clauses for that.

Now what if we must return something that is really optional like in our discount coupon example, how do we do this
without breaking the rule?

Special case pattern

One way to avoid returning null is to return a concrete implementation of the returned type that does nothing. This
technique is known as the special case pattern. Here is an
example from our previous scenario:

// Default implementation:
public class RandomDiscountCoupon : IDiscountCoupon
{
  private readonly Random _random = new Random();

  public void ApplyDiscount(Order order) =>
    order.TotalPrice -= order.TotalPrice * _random.Next(5, 25) / 100;
}

// Special case implementation:
public class ZeroDiscountCoupon : IDiscountCoupon
{
  public void ApplyDiscount(Order order) {}
}

The important point here is that the special case class should be able to be used like any other implementations:

public void ApplyMonthlyDiscount(Order order)
{
  var coupon = GetMonthlyDiscountCoupon();
  // No null checks and no special conditions specific to `ZeroDiscountCoupon`.
  coupon.ApplyDiscount(order);
}

This technique is very simple to understand and implement and should be used when possible, but in some scenarios, it
cannot be used. Let's tackle one of these with a more complex but more powerful approach.

Optional object pattern

In some cases, the above solutions will not work and we will have to pull out more power and use the optional object
pattern. Imagine we want our previous discount coupon to have a code and be attached to the order. In
the previous special case implementation it does not make any sense:

// Interface:
public interface IDiscountCoupon
{
  // Added code property.
  string Code { get; }

  void ApplyDiscount(Order order);
}

// Special case implementation:
public class ZeroDiscountCoupon : IDiscountCoupon
{
  string Code { get; } = "";

  public void ApplyDiscount(Order order) {}
}

It does not look so bad, but it does not make much sense to attach a coupon with an empty code to the order:

public void ApplyMonthlyDiscount(Order order)
{
  var coupon = GetMonthlyDiscountCoupon();
  coupon.ApplyDiscount(order);
  order.AttachCoupon(coupon);
  // Considering `order.AttachCoupon()` internally invokes `order.Coupon = coupon`,
  // `order.Coupon.Code` may now be an empty string.
}

A better solution is to return an optional object from GetMonthlyDiscountCoupon and to turn Order.Coupon into an
optional as well:

// 1) Return an optional object from `GetMonthlyDiscountCoupon`.
public Optional<IDiscountCoupon> GetMonthlyDiscountCoupon()
{
  if (MonthlyDiscountAlreadyUsed()) return Optional.None<IDiscountCoupon>();
  return Optional.Some(new RandomDiscountCoupon());
}

public class Order
{
  // 2) Turn `Order.Coupon` into an optional.
  public Optional<IDiscountCoupon> Coupon { get; private set; } = Optional.None<IDiscountCoupon>();

  // Bonus tip: Use mutation methods and private setters to preserve encapsulation.
  public void AttachCoupon(IDiscountCoupon coupon) => Coupon = Optional.Some(coupon);
}

With this in place, the caller cannot access the coupon value directly and so is forced to make a decision:

public void ApplyMonthlyDiscount(Order order)
{
  var optionalCoupon = GetMonthlyDiscountCoupon();
  // Evaluated if the coupon is present.
  optionalCoupon.MatchSome(coupon =>
  {
    coupon.ApplyDiscount(order);
    order.AttachCoupon(coupon);
  })
  // Otherwise, `order.Coupon` will remain none.
}

Unfortunately, unlike Java, C# lack the Optional<T> type. Implementing such a pattern is out of the scope of this
article but you take a look at Zoran Horvat's great implementation.

But remember with great power comes great responsibility. This means implementing this pattern also means maintaining
additional code.

An alternative would be to use an open-source implementation such as
Optional in C#.

Guard Clauses Explained
Enabling C# Nullable Reference Types in the Whole Solution
How to Reduce Cyclomatic Complexity Part 5: Option Functional Type by Zoran Horvat
Custom Implementation of the Option/Maybe Type in C# by Zoran Horvat

CQRS Scalable Aggregates

Maxime Gélinas — Tue, 15 Sep 2020 19:16:06 +0000

Aggregates are the heart of your system. They hold domain logic and are responsible for emitting events that will
eventually make your data consistent across multiples data projections and bounded contexts. Because aggregates are so
important, it is crucial to keep them small and easy to understand, but how to do this when the domain gets bigger and
bigger?

In this article, I will show you a way to reduce complexity from your aggregates and make them scale better.

Write-side domain overview

Before getting started, let review how commands are executed and turned into events.

After receiving the command sent by the user, the command handler invokes the repository to load the aggregate state in
memory. Then, the command is executed on the aggregate which emits either domain events or failures. Finally, those
events or failures are persisted using the repository.

e.g.

[👤 Coder]
  -> [📨 Comment issue command]
  -> [📫 Comment issue handler]
  -> [🍇 Issue aggregate]
  -> [📅 Issue commented event]

First attempt

In the first place, I will show you briefly how the write-side domain was implemented in a real-world project a worked
on. Then, we will discuss the scaling issues of this solution and how it can be improved to keep your aggregates clean.

Here is how it looks:

public class CommentIssue : ICommand
{
  public CommentIssue(Guid issueId, string message)
  {
    IssueId = issueId;
    Message = message;
  }

  public Guid IssueId { get; }
  public string Message { get; }
}

public class CommentIssueHandler : ICommandHandler<CommentIssue>
{
  private readonly IRepository<Issue> _repository;

  public CommentIssueHandler(IRepository<Issue> repository) => _repository = repository;

  public void Handle(CommentIssue command)
  {
    // 1. Loads the aggregate in memory.
    var issue = _repository.Find(command.IssueId);
    // 2. Invokes the aggregate method.
    issue.Comment(command.message);
    // 3. Saves the aggregate.
    _repository.Save(issue);
  }
}

public class Issue : AggregateRoot<Issue, Guid>
{
  private readonly ISet<IssueComment> _comments = new HashSet<IssueComment>();

  public Issue(Guid id) : base(id) { }

  public IEnumerable<IssueComment> Comments => _comments;

  public void Comment(string message)
  {
    if (string.IsNullOrWhiteSpace(message)) return;
    // `Emit()` internally invokes `Apply()` to avoid code duplication.
    Emit(new IssueCommented(new IssueComment(message)));
  }

  // All other command related methods go here e.g.
  // `public void Edit() { }`
  // `public void Close() { }`
  // `public void Unsubscribe() { }`

  protected override void Apply(IDomainEvent @event)
  {
    // This could be done using reflexion, but be aware of performance issues.
    switch (@event)
    {
      case IssueCommented e: Apply(e); break;
    }
  }

  private void Apply(IssueCommented @event) =>
    _comments.Add(new IssueComment(@event.CommentId, @event.Message));
}

public class IssueCommented : IDomainEvent
{
  public IssueCommented(Comment comment)
  {
    CommentId = comment.Id;
    Message = comment.Message;
  }

  public Guid CommentId { get; }
  public string Message { get; }
}

As you can see, using this technique, the aggregate grows for every command we add. Because of this, it is easy to
imagine how fast this newly created aggregate will turn into a hard to maintain mess as our domain grows.

Also, all command handlers will do the exact same things i.e.:

Loads the aggregate in memory.
Invokes the aggregate method.
Saves the aggregate.

Let see how we can fix this!

Refactored solution

The trick is to let the commands and events execute/apply themselves!

public class CommentIssue : ICommand<Issue>
{
  public CommentIssue(Guid issueId, string message)
  {
    IssueId = issueId;
    Message = message;
  }

  public Guid IssueId { get; }
  public string Message { get; }

  // Commands now know how to execute themselves.
  public IEnumerable<IDomainEvent<Issue>> ExecuteOn(Issue aggregate)
  {
    if (string.IsNullOrWhiteSpace(Message)) yield break;
    yield return new IssueCommented(new IssueComment(IssueId, Message));
  }
}

public class IssueCommented : IDomainEvent<Issue>
{
  public IssueCommented(IssueComment comment)
  {
    CommentId = comment.Id;
    Message = comment.Message;
  }

  public Guid CommentId { get; }
  public string Message { get; }

  // Events now know how to apply themselves.
  public void ApplyTo(Issue aggregate) =>
    aggregate.Comments.Add(new IssueComment(CommentId, Message));
}

By doing this, we are able to implement a new Execute() method in the aggregate base class which will execute a
command and apply the returned events.

Also, it makes it possible to generalize the Apply() method and move it up to the aggregate base class.

public abstract class AggregateRoot<TSelf, TId> : Entity<TSelf, TId>, IAggregateRoot<TId>
  where TSelf : AggregateRoot<TSelf, TId>
{
  private readonly List<IDomainEvent<TSelf>> _uncommittedEvents = new List<IDomainEvent<TSelf>>();

  // ...

  public void Apply(IDomainEvent<TSelf> @event) => @event.ApplyTo((TSelf)this);

  public void Execute(ICommand<TSelf> command)
  {
    var events = command.ExecuteOn((TSelf)this);
    _uncommittedEvents.AddRange(events);
    foreach (var @event in events) Apply(@event);
  }
}

Now that we added the Execute() method we can invoke it right away from the command handler.

Also, you can see below, our command handler is now named IssueCommandsHandler instead of CommentIssueHandler. Why
is that? This is because we simplified enough that all command handlers will be exactly the same so we can use the same
command handle for all commands.

public class IssueCommandsHandler : ICommandHandler<CommentIssue, Issue>
{
  private readonly IRepository<Issue, Guid> _repository;

  public IssueCommandsHandler(IRepository<Issue, Guid> repository) => _repository = repository;

  public void Handle(CommentIssue command)
  {
    var issue = _repository.Find(command.IssueId);
    // The command can now be executed directly on the aggregate.
    issue.Execute(command);
    _repository.Save(issue);
  }
}

Our objective was to clean up our aggregate and as you can see below there is nothing left in it so I think we made it!

public class Issue : AggregateRoot<Issue, Guid>
{
  public Issue(Guid id) : base(id) { }

  public ISet<IssueComment> Comments { get; } = new HashSet<IssueComment>();

  // Only common validations/business rules go here!
}

Note that I exposed Comments.Add() through the ISet interface for simplicity purposes. In a real-world project,
consider adding a custom collection class such as IssueComments to hold custom business rules.

The source code can be found
here.

Implementing an Event Sourced Aggregate by Nick Chamberlain
Command Handlers by Nick Chamberlain

Guard Clauses Explained

Maxime Gélinas — Tue, 15 Sep 2020 19:09:22 +0000

What is a guard clause?

A guard clause is a technique derived from the fail-fast method whose purpose
is to validate a condition and immediately stop the code execution if the condition is not met by throwing a meaningful
error instead of leaving the program to throw a deeper and less meaningful error. Let me show you an example:

public User GetUser(string userName)
{
  if (userName == null) throw new NullArgumentException(nameof(userName));
  // Continue if the condition is fulfilled...
}

In the previous example, the if block act as a guard clause by protecting the GetUser method against any null
userName arguments. Like that, we are free to write the rest of the method without having to worry about checking if
userName is null.

Why using guard clauses?

Guard clauses simplify code by removing useless nested branching conditions, by returning meaningful errors.

Before guard clauses:

public void CreateUser(string userName, string password)
{
  if (userName == null)
  {
    // Do something...
  }
  else
  {
    // Do something else...
    if (password == null)
    {
      // Do something...
    }
    else
    {
      // Do something else...
    }
  }
}

After guard clauses:

public void CreateUser(string userName, string password)
{
  if (userName == null)
    throw new NullArgumentException(nameof(userName));
  if (password == null)
    throw new NullArgumentException(nameof(password));
  // Do something...
}

What to guard against?

Preconditions

Preconditions are the conditions that have to met before the method execution. Basically, the method preconditions will
always depend on the method arguments. A good example of a method precondition is a non-null argument.

public User GetUser(string userName)
{
  // Requires a non null `userName` argument.
  if (userName == null) throw new NullArgumentException(nameof(userName));
  // Execute the method purpose...
}

Postconditions

Postconditions are the conditions that have to met after the method execution. Basically, the method postconditions will
always depend on the value returned by the method. A good example of a method post-condition is a non-null or a not
empty string.

public User GetUsers()
{
  // Execute the method purpose:
  var users = this._repository.GetUsers();
  // Ensures `UserRepository.GetUsers()` returns no null users.
  if (users.Any(user => user == null))
    throw new Exception("UserRepository.GetResult() a null user.");
  return users;
}

As you can guess, post-conditions are not mandatory since you know exactly what's coming out of the method. The only
time you should consider using post-conditions is when you have to use unreliable calls (i.e. external methods or
protected methods) to get the result of the method as the example above.

Public vs private

In both cases, preconditions and post-conditions should not be checked for private methods since the class itself is the
caller of these methods, you can trust what goes in goes and out of them. So you don't have to validate them.

How to handle guard clauses exceptions?

Ok, it's time to introduce a very important rule about guard clause:

Guard clauses exceptions should never be caught.

What this means is that most of the time, you should let the caller hit those exceptions because most of the time, guard
clauses will guard against scenarios that should never happen like null arguments. What a null argument means? Most of
the time, a null argument is a bug so should we catch a bug and taking the chance of never discover it? No! Instead, we
want to let the application fail immediately so that we can discover the bug before deploying it to production during
the development process.

But what if we have preconditions that don't rely on bugs? What if we have preconditions that could occur sometimes like
business logic preconditions? The solution is to expose your guard clauses!

Why exposing guard clauses?

Sometimes, you have to guard against business logic which means the condition may not be respected and it's not
necessarily a bug. In those cases, a possibility is to expose the related guard clauses under a public boolean method to
let the caller branch around this boolean method.

Implementation:

public bool CanCreateUser(string userName, string password)
{
  return !this.UserNameExists(userName) && this.IsStrongPassword(password);
}

public void CreateUser(string userName, string password)
{
  if (!this.CanCreateUser(userName, password))
    throw new Exception("The user can't be created.");
  // Create the user...
}

Usage:

if (!CanCreateUser(userName, password))
{
  Console.WriteLine("Invalid username or password.");
  return;
}
CreateUser(userName, password);
Console.WriteLine("The user has been successfully created.");

Why creating a guard class

It's a good practice to encapsulate our guard clauses inside a class dedicated to providing guard clauses so we could
reuse the logic and write more readable guard clauses. Here is an example of such a class:

public static Guard
{
  public static void Requires(Func<bool> predicate, string message)
  {
    if (predicate()) return;
    Debug.Fail(message);
    throw new GuardClauseException(message);
  }

  [Conditional("DEBUG")]
  public static void Ensures(Func<bool> predicate, string message)
  {
    Debug.Assert(predicate(), message);
  }
}

In that implementation, the Requires method is used to validate preconditions and the Ensures metd is to validate
post-conditions. The interesting point about this implementation is the use of the C# Debug class coming from the
System.Diagnostics namespace. The main point of the Debug class is that it will execute in debug mode only and can't
be caught by the caller so it's respect the "never catch guard clauses exceptions" rule. Also, the Ensures method uses
the Conditional C# attribute to make sure the code inside the method will run in debugging only so the performance
will not be affected in production because remember the guard clauses bugs will be detected before deploying in
production! But just to be sure, we protect ourselves in the Requires method by throwing a GuardClauseException if the
precondition isn't met because the code after it will probably fail anyway or cause data inconsistency we don't want.

After all, here how we could use the Guard class:

public User GetUserRange(int from, int to)
{
  Guard.Requires(() => from >= 0, "Received negative from.");
  Guard.Requires(() => to >= 0, "Received negative to.");

  var users = this._repository.GetUsers();
  foreach (user in result)
    Guard.Ensures(
      () => user != null,
      "UserRepository.GetResult() a null user.");

  return users;
}

Summary

In this article, we have seen how guard clauses can help us to discover bugs before deploying in production and to make
our code more readable.

We have also learned, why guard clauses exceptions should never be handled and how to expose guard clauses as a
draw-back when they rely on business logic.

Finally, we learned how to create our own guard clauses implementation under the Guard class.

DEV Community: Maxime Gélinas

Never Return Null Again

What is wrong with `null`?

Establishing the rule

Special case pattern

Optional object pattern

Related

CQRS Scalable Aggregates

Write-side domain overview

First attempt

Refactored solution

Related

Guard Clauses Explained

What is a guard clause?

Why using guard clauses?

What to guard against?

Preconditions

Postconditions

Public vs private

How to handle guard clauses exceptions?

Why exposing guard clauses?

Why creating a guard class

Summary

DEV Community: Maxime Gélinas

Never Return Null Again

What is wrong with null?

Establishing the rule

Special case pattern

Optional object pattern

Related

CQRS Scalable Aggregates

Write-side domain overview

First attempt

Refactored solution

Related

Guard Clauses Explained

What is a guard clause?

Why using guard clauses?

What to guard against?

Preconditions

Postconditions

Public vs private

How to handle guard clauses exceptions?

Why exposing guard clauses?

Why creating a guard class

Summary

What is wrong with `null`?