Enterprise Software Development

Azure DevOps

2019-12-17T05:00:00-06:00

I guess you all have heard of continuous integration / continuous delivery (CI/CD). In this post, I want to show to you a tool for CI/CD (and more): Azure DevOps. I want to focus on three most important parts of Azure DevOps: Boards, Repos and Pipelines.

Boards

That’s where you manage and track your work items. It supports different processes for Kanban, Scrum, etc. It’s pretty much what you expect it to be. One great feature is, that you can create a new branch for your work item directly from the board view - it’s integrated with your source code repository.

Repos

Repos is about your code. You can either create a private repository or use a GitHub repository. You can manage your files, browse the commit history or create pull requests.
You can also define policies. For example, you can disallow direct commits to the master branch. That way, you have to use pull requests. Another good idea is to enable build validation for the master branch. You don’t want anyone to pull something into master that doesn’t compile or doesn’t pass all the tests. If you want to enable build validation, you need a build pipeline.

Pipelines

Here you create and run your build and release pipelines. There are several predefined build agents that will work for many different project types, but you can also create self-hosted agents.
Pipelines together with Repos is the foundation for CI/CD. You can automatically build and deploy whenever your source code changes.

Conclusion

I love Azure DevOps - it’s a great tool. There are two aspects I like the most:

It’s integrated: I really like how Boards, Repos and Pipelines work together. As a developer, you need only one tool for managing your day to day work. When you’re ready to start a new work item, you go to Boards. You mark the work item as “in progress” and create a feature branch directly from the board. Once you’re finished, you create a pull request. Your team members can review the pull request in Repos and give you feedback. When the pull request is merged, it automatically triggers a build and a subsequent release. You can check whether the build and release were successful in Pipelines. If everything is okay, you can go back to Bords and start working on the next item.

It’s a service: I need to focus on software development - not on maintaining a server. Yes, there are scenarios where you can’t (or don’t want to) rely on a third-party service - point taken. But whenever it is an option, I go with the service. I don’t want to be bothered with hosting related details. That’s not my job. I just need it to work.

Do You Need to Host It Yourself?

There’s an on-premise version called Azure DevOps Server. It’s the latest version of Visual Studio Team Foundation Server with a new name.

Have you tried out Azure DevOps yet? What do you think about it? Do you prefer to host your own on-premise server?

Farewell TFVC - It’s Time for Git

2019-12-10T05:00:00-06:00

I admit it. I’ve been very late to the Git train. But I managed to jump aboard - and I love it. I’m sorry TFVC, we had many good years together. I always defended you and I couldn’t imagine how another version control did anything better than you. But then I tried out Git.

This post isn’t a detailed comparison between Git and TFVC. And it’s also not a step by step guide on how to switch from TFVC to Git. This post is targeted at all the TFVC-using developers out there who have never tried out Git - maybe you should give Git a chance and see for yourself whether you like it or not.

How to Set It Up

You can set up your own on-premise Git sever if you want to (or have to). But I’d consider using either GitHub for open source projects or Azure DevOps with a Git repository. (Btw., you can use Azure Devops with a GitHub repository as well.)

Do you use Visual Studio? No problem, Visual Studio supports Git.
Do you use Visual Studio Code? No problem, Visual Studio Code supports Git.

Let’s have a look at how to use Git for your daily work.

Yes, It’s Different

When you search for Git examples on the internet, you’ll notice that they all use console commands. The console is how you can use the full feature set of Git. If you’re used to the graphical interface for TFVC in Visual Studio, you might be discouraged. But, as I’ve already said, Visual Studio supports Git. That means, there’s a graphical interface for Git to. For your daily workflow, the graphical interface is more than sufficient. There’s no need to use the console if you don’t want to. Once you know Git better, you’ll find the console commands to be straight forward and easy to use.

A roadblock when coming from TFVC is the different vocabulary. Here’s a simple translation table (beware that it’s not always possible to accurately translate between TFVC and Git):

Action	TFVC	GIT
Inspect changes on the server	-	FETCH
Download changes from the server	GET	PULL
Commit changes	-	COMMIT
Upload changes to the server	CHECKIN	PUSH
Download and upload changes from/to the server	-	SYNC
Create a branch	BRANCH	BRANCH
Switch branch	-	CHECKOUT
Merge branches	MERGE	MERGE

As you can see, Git has some commands TFVC doesn’t have. That’s because Git works quite differently under the hood: TFVC is a centralized version control, Git is a decentralized version control.

TFVC: There’s one version control server. The clients download files from the server to their machine, make some changes and then upload the modified files back to the server. That’s pretty much it.

Git: Every client has its own version control up and running on its machine. Technically, there’s no need for a central server - that’s why Git is decentralized. However, in most companies you do have a central repository - that’s the GitHub or Azure DevOps repository.
Switching to a branch is called checkout. You can either switch to a local branch or you can checkout a remote branch. When you check out a remote branch, you’re not only downloading all the files. You’re also downloading all the file histories. That means, after the checkout you’ve got a complete copy of the remote branch on your local machine. Therefore, you don’t need a connection to the remote repository until you want to push your changes to the central repository. If you want to push something to the central repository, you have to commit your changes to your local repository first. Then, you can push your modified branch to the server.
Ok, so I can access the file history without a connection to the central server? That’s nice, but is that all? No, there are other cool things you can do when you’ve got your own version control running. For example, you can create local branches. You want to try something out? No problem, create a local branch. If it turns out to be good, merge it into your development branch. If not, delete the branch. Branches are a powerful tool. But you have to know that Git branches are way better than TFVC branches.

Why Git Is Better

I tried to explain what’s the principal difference between TFVC and Git. Now, I’d like to lay out why I think that Git is better than TFVC.

It’s decentralized: Having a local version control running is great. You can do a lot of cool things that way.

Branches are light: I already mentioned branches and how great it is to create a new branch whenever you want to. But when you’re used to TFVC branches, you probably don’t see how cool that is. That’s because TFVC branches are heavy. Every time you create a new branch, all the files from the source branch get copied to a new folder on your disk. That’s no problem for very small project, but for real-world enterprise projects, that can take some time. And if you’ve got multiple branches, it can also consume a lot of disk space. Because of that, you don’t have a lot of branches when using TFVC. You have a master branch and probably one branch for every release (V1, V1.1, V2, …). That’s it. Creating a branch is an endeavor. You don’t do it light-heartedly.
That’s very different with Git. Git Branches are light. When you create a new branch with Git, it’s only a pointer to a certain commit. That’s it. There’s nothing to copy.

Every commit points to its previous commit (its parent). Here, the first commit is 1, followed by 2 and so on. When you switch from one branch to another, let’s say from master to feature, Git restores the files in your working directory accordingly. That means, Git has to undo commits 5 and 3 and redo commit 4. Git does that in a very smart way. Changing branches is almost seamless. When you checkout a branch with Git, you don’t switch your working directory like you would do when using TFVC.

Pull requests are awesome: How do you merge branches with TFVC? First, you download both branches to your machine (Yuck!). Then, you merge the two branches locally und check in the merged branch. You can do the same with Git (but downloading the two branches is way faster). However, there’s another way. You can create a pull request.
A pull request is a collaborative merge. You don’t merge the branches locally, you create a pull request on the server. Now, your team members can review the merge and give you feedback before the changes get committed.

Do you want to know more about how Git works under the hood? Check out Pro Git.

A Typical Development Workflow with Git

Last, I want to show to you what a typical development workflow with Git might look like. Imagine you have to implement a new feature (user story, task, …). But you’re not on your own, you work together with some team members.

1) You create a new feature branch on the server.
Since you work together with others, it’s a good idea to create the feature branch on the server. If you work alone, you can also create a local branch and push the branch to the central repository later. Feature branches are great. You can implement a feature without interfering with the main branch. The feature gets merged into the main branch when it’s ready.

2) You check out the remote branch.
Now, you can start coding. Push your changes to the remote feature branch frequently. That way you can work together with your team members effectively.

3) Create a pull request.
Once you and your team members have finished the implementation, you create a pull request for your feature on the server. That way, you can get some feedback on your code.

4) Complete the pull request.
Once the pull request is approved, the feature gets merged into the main branch.

That’s it! Let’s do it all again with the next feature.

Do you still use TFVC? Do you think it’s time to move on to Git? Or is TFVC just the right version control for you?

More Fun with Caching

2019-12-03T05:00:00-06:00

In the last post we had some fun playing around with an object-oriented implementation of a simple cache. Today, I want to have some more fun building a cache - but this time, we’ll make things more functional.

This post is a sequel to the last post, you might want to go back and read the motivation if you haven’t already.

Higher-Order Functions

A higher-order function is a function that accepts a function as a parameter or returns a function as result.

Alright, but how can we use that for our cache implementation? Do you recall the object composition implementation? We had the following interface:

public interface Executor<TKey, TValue>
{
    TValue Execute(TKey key);
}

That’s a strange interface, don’t you think? It contains only one method and both the interface and the method have almost the identical name. What’s the purpose of that interface? We need some way to make sure that the object someone’s passing to our cache constructor has a public method called ‘Execute’. In fact, we’re only interested in the method. The interface is a mere necessity - there’s no other way to express it in a pure object-oriented language.

But C# isn’t a pure object-oriented language - there’s a lot of functional influence.

Delegates

C# supports higher-order functions since its early days. Functions that can be passed around like objects are called delegates. Here’s how we can implement the cache using a delegate instead of an interface:

public delegate TValue Execute<TKey, TValue>(TKey key);

public class Cache<TKey, TValue> where TKey : notnull
{
    readonly Execute<TKey, TValue> Executor;
    readonly Dictionary<TKey, TValue> entries = new Dictionary<TKey, TValue>();

    public Cache(Execute<TKey, TValue> executor)
    {
        Executor = executor;
    }

    public TValue GetValue(TKey key)
    {
        if (!entries.TryGetValue(key, out TValue value))
        {
            value = Executor(key);
            entries.Add(key, value);
        }
        return value;
    }
}

There’s no need for an interface anymore. The constructor parameter executor is a delegate now. That simplifies the usage of the cache. We just pass the method we want to be cached when we are composing the cache instance:

var squareCache = new Cache<int, int>(CalculateSquare);
PrintSquares(numbers, squareCache);

Having an explicit delegate definition is a good thing in certain scenarios. You can assign a meaningful name to the delegate itself and to every parameter of the delegate. However, in other scenarios there isn’t a point in having an explicit delegate. Let’s take the delegate from our example. Execute isn’t a particularly meaningful name, and key isn’t either. In such situations, it’s better to use one of the many general-purpose delegates of the framework.

Here’s the cache implementation with a general-purpose Func delegate:

public class Cache<TKey, TValue> where TKey : notnull
{
    readonly Func<TKey, TValue> Executor;
    readonly Dictionary<TKey, TValue> entries = new Dictionary<TKey, TValue>();

    public Cache(Func<TKey, TValue> executor)
    {
        Executor = executor;
    }

    public TValue GetValue(TKey key)
    {
        if (!entries.TryGetValue(key, out TValue value))
        {
            value = Executor(key);
            entries.Add(key, value);
        }
        return value;
    }
}

When there’s no benefit in using an explicit delegate, you should use a general-purpose delegate. The usage of the cache is the same as with the explicit delegate.

That’s it. We’ve seen many different ways to implement a cache, but that’s ultimately how I would write a simple cache in C#. What do you think about it? How would you implement a cache?

F#

When we’re talking about higher-order functions already, why not take it one step further and talk about a functional cache implementation? From here on, I switch to F#.

Cache Class

First, let’s translate the final version of the C# implementation to F# and see how it looks:

type Cache<'key, 'value when 'key : equality> (executor) =
    let entries = Dictionary<'key, 'value> ()
    
    member _.GetValue key =
        match key |> entries.TryGetValue with
        | true, value -> value
        | _ ->
            let value = key |> executor
            (key, value) |> entries.Add
            value

As you can see, it’s absolutely possible to write classes in F#. Just like C# isn’t a pure object-oriented language, F# isn’t a pure functional language.

A quick remark: F# isn’t made to write classes, nevertheless, the F# version is more compact than the C# version. That’s something you experience all the time when you compare F# code to C# code: the C# code is more verbose. One reason is the better type inference of F#. In a lot of cases, the compiler can figure out the correct type itself, you don’t have to sprinkle type information all over your code like you have to with C#.

Cache Method

Although it’s possible to write a cache class in F#, it’s not very functional. Maybe we should start from scratch. Here’s calculateSquare in F# (I add the method signatures in comments for clarity):

//  int -> int
let calculateSquare number = number * number

How do we cache that? In functional programming, we don’t like side effects. In the cache class, entries gets modified every time there’s a cache miss. That’s a side effect. If we want no side effects, we can’t modify the cache. We have to return a new cache based on the old cache but including the new cached item. A cache method might look like this:

//  ('a -> 'b) -> Map<'a, 'b> -> 'a -> Map<'a, 'b>
let cache executor entries key =
    if entries |> Map.containsKey key then
        entries
    else
        entries |> Map.add key (key |> executor)

Here, the cache is just a Map. When we call cache, we pass the current cache as the parameter entries and the result of cache is the new cache. If there’s already a cache entry in entries for key, cache simply returns entries. Else, cache invokes executor and adds the result to entries - the result of Map.add is new Map that includes all the old entries plus the new entry. That new Map is returned.

Quick question: Is cache pure? That depends on executor. If executor is pure, cache is pure. If executor is impure, cache is impure.

Let’s have a look at how you can use the cache method:

//  Map<int, int> -> (seq<int> -> Map<int, int>)
let calculateSquares squares =
    Seq.fold (cache calculateSquare) squares

//  Map<int, int> -> seq<int> -> unit
let printSquares squares numbers =
    calculateSquares squares numbers
    |> Map.iter (fun number square -> printf "%d * %d = %d" number number square)

If you don’t know F#, you might notice the lack of type information. As I already mentioned, the F# type inference can figure out the right types on its own in a lot of cases.

But what’s the advantage of this approach?
First, it’s very compact and direct. Every other approach is way more verbose.
Second, it’s easy to test. The cache is nothing but a simple data structure - it’s a Map. If you want to test the code with an empty cache, pass an empty Map. If you want to test the code with a populated cache, set up a Map accordingly and use it as parameter squares.

How can you test your code with the cache class approach? How do you populate a cache object? There are basically two ways.
First, you can populate the cache by calling GetValue and thereby populate the cache as a side effect. However, if the cached action takes a relevant time to execute, that increases the time your test takes to run significantly.
Second, you can use a mock object instead of the real cache object. That’s how you usually do it. But mocking an object comes with a not to be underestimated overhead. You likely have to define an additional interface ICache and change your code to reference ICache instead of Cache. Then, you can use the real cache object in production and a mocked cache for testing. But we’ll talk more about testing in another post.

So … when the functional approach has such desirable properties, you might ask: Can we do the same with C#? Yes, but … have a look:

public static int CalculateSquare(int number) => number * number;

public static ImmutableDictionary<TKey, TValue> Cache<TKey, TValue>(
    Func<TKey, TValue> executor, ImmutableDictionary<TKey, TValue> entries,
    TKey key) =>
        entries.ContainsKey(key) ?
            entries :
            entries.Add(key, executor(key));

public static ImmutableDictionary<int, int> CalculateSquares(
    ImmutableDictionary<int, int> squares, IEnumerable<int> numbers) =>
        numbers.Aggregate(squares,
            (squares, number) => Cache(CalculateSquare, squares, number));

public static void PrintSquares(ImmutableDictionary<int, int> squares,
    IEnumerable<int> numbers)
{
    foreach (var (number, square) in CalculateSquares(squares, numbers))
    {
        Console.WriteLine($"{number} * {number} = {square}");
    }
}

Here’s the F# code again for an easier comparison with the C# code:

let calculateSquare number = number * number

let cache executor entries key =
    if entries |> Map.containsKey key then
        entries
    else
        entries |> Map.add key (key |> executor)

let calculateSquares squares =
    Seq.fold (cache calculateSquare) squares

let printSquares squares numbers =
    calculateSquares squares numbers
    |> Map.iter (fun number square -> printf "%d * %d = %d" number number square)

Which one do you prefer?

As you can see, it’s absolutely possible to do the same with C#, but the code is way more verbose. To be honest, I find the C# code to be very difficult to read. If you want to write functional code, I strongly suggest using a functional language.

What do you prefer? The object-oriented or the functional approach? Or would you do it completely different?

C# Fun with Caching

2019-11-26T05:00:00-06:00

When was the last time you had some fun playing around with code? I hope it wasn’t too long ago. Unfortunately, there are a lot of professional developers who have lost fun and excitement somewhere along the way. Can you remember how much fun it all was when you started out? We shouldn’t lose that - despite all the deadlines, overflowing ticket queues and all the other stuff we have to face in our professional life.

So, in this post I want to play around with code and have some fun. Maybe, there’s even something we can learn ;-)

Motivation

Let’s start with the motivation for this post. Suppose we have the following code (I ignore exception handling to improve readability):

public static async IAsyncEnumerable<string> FetchResources(
    IAsyncEnumerable<Uri> resourceUris)
{
    await foreach (var resourceUri in resourceUris)
    {
        yield return await FetchResource(resourceUri);
    }
}

public static async Task<string> FetchResource(Uri resourceUri)
{
    using var client = new HttpClient();
    var response = await client.GetAsync(resourceUri);
    return await response.Content.ReadAsStringAsync();
}

FetchResources takes the URIs from the async stream resourceUris, calls FetchResource and returns the result as an item of another async stream. Suppose FetchResource takes a relevant time to execute and there might be duplicate URIs in resourceUris. Now, to improve performance, we want to cache the results of FetchResource - like your web browser caches pages. That’s the goal of this post: implement a simple cache.

I want to focus on the cache and not get distracted by async streams and HTTP requests. That’s why I’ll simplify the example. For the rest of the post, we’ll work with the following code - but keep the initial version in mind:

public static void PrintSquares(IEnumerable<int> numbers)
{
    foreach (var number in numbers)
    {
        var square = CalculateSquare(number);
        Console.WriteLine($"{number} * {number} = {square}");
    }
}

public static int CalculateSquare(int number) => number * number;

FetchResources becomes PrintSquares and FetchResource becomes CalculateSquare. Now, the goal is to cache the results of CalculateSquare. How would you do it?

Direct Approach

KISS, right? Add a static dictionary and use it in CalculateSquare:

public static readonly Dictionary<int, int> squares = new Dictionary<int, int>();
public static int CalculateSquare(int number)
{
    if (!squares.TryGetValue(number, out var square))
    {
        square = number * number;
        squares.Add(number, square);
    }
    return square;
}

Okay … okay … you could do that. But I wouldn’t recommend it. Or to put it different: Don’t do that!

First, introducing static state is a terrible idea. If you keep doing that, soon your system will be unmanageable. Who controls the cache? Eventually, you’ll have to remove items from the cache to limit memory usage - keep in mind, CalculateSquare is only a placeholder for a more complex method. And btw, if you use a static Dictionary, CalculateSquare is no longer thread safe. You would need to use a ConcurrentDictionary or to implement locking.
Second, CalculateSquare does two things now. Calculate the square number and cache the result. But methods should do only one thing. In this case, the actual calculation and the caching are two separate things. In a real-life scenario, we want to have control over the caching strategy independent of the executed method. Do we want to cache at all? How long do we want to keep the cached results? Do we want to have separate caches for separate concerns? You don’t have that control if you do the caching inside the method that should be cached.

So, let’s discard the direct approach and go back to the clean and simple version of CalculateSquare:

public static int CalculateSquare(int number) => number * number;

In that form, CalculateSquare truly does only one thing.

The Caller Caches

When we don’t want CalculateSquare to do the caching, why not move the cache one level higher and cache at the level of PrintSquares? That would look like this:

public static void PrintSquares(IEnumerable<int> numbers)
{
    var squares = new Dictionary<int, int>();

    foreach (var number in numbers)
    {
        if (!squares.TryGetValue(number, out var square))
        {
            square = CalculateSquare(number);
            squares.Add(number, square);
        }
        Console.WriteLine($"{number} * {number} = {square}");
    }
}

That’s better than the direct approach. At least we don’t have a static Dictionary. But, again, we don’t have control over the cache. There’s a new cache instance whenever you call PrintSquares. Now that’s easy to fix:

public static void PrintSquares(IEnumerable<int> numbers,
    Dictionary<int, int> squares)
{
    foreach (var number in numbers)
    {
        if (!squares.TryGetValue(number, out var square))
        {
            square = CalculateSquare(number);
            squares.Add(number, square);
        }
        Console.WriteLine($"{number} * {number} = {square}");
    }
}

Okay, now it’s up to the caller whether he or she passes and empty or a populated cache. That’s improvement.
You might ask, how much further up do we play the same game and make squares a method parameter? Simple answer: As far up as necessary. Eventually, someone has to initialize squares, but I don’t think it’s the responsibility of PrintSquares.
However, PrintSquares is still doing two things - print the square numbers and cache the results. Let’s separate those two things.

A Cache Object

Maybe your first intuition when faced with the challenge to implement caching was to create a cache class. That’s what I’m going to do now.

SquareCache

I want to begin with the obvious approach and define a SquareCache class:

public class SquareCache
{
    readonly Dictionary<int, int> squares = new Dictionary<int, int>();

    public int CalculateSquare(int number)
    {
        if (!squares.TryGetValue(number, out var square))
        {
            square = CalculateSquare(number);
            squares.Add(number, square);
        }
        return square;
    }
}

Now, we’ve extracted the code for caching and put in into a separate class. Let’s see how we can use SquareCache:

public static void PrintSquares(IEnumerable<int> numbers, SquareCache squareCache)
{
    foreach (var number in numbers)
    {
        var square = squareCache.CalculateSquare(number);
        Console.WriteLine($"{number} * {number} = {square}");
    }
}

PrintSquares looks good now. The caller has full control over the cache we use by passing the cache object squareCache and we got rid of the caching code inside of PrintSquares. I’m satisfied with how PrintSquares turned out - I don’t see the need for any further improvement.

But what about SquareCache? If all you want to cache is CalculateSquare, it’s alright. But what if you want to cache something else as well? Why not separate the caching code from the method we want to cache?

Inheritance

Let’s start with a classic object-oriented approach. An abstract base class and a derived concrete class:

public abstract class Cache<TKey, TValue> where TKey : notnull
{
    readonly Dictionary<TKey, TValue> entries = new Dictionary<TKey, TValue>();

    public TValue GetValue(TKey key)
    {
        if (!entries.TryGetValue(key, out TValue value))
        {
            value = Execute(key);
            entries.Add(key, value);
        }
        return value;
    }

    protected abstract TValue Execute(TKey key);
}

public class SquareCache : Cache<int, int>
{
    protected override int Execute(int number) => CalculateSquare(number);
}

That’s a common way to model something in an OO language. However, it’s a bit clumsy. You have to derive a new concrete class every time you want to cache something else. If you don’t have many different things to cache anyway, that might be ok.
Let’s have a look at how we would use the new version of SquareCache:

public static void PrintSquares(IEnumerable<int> numbers, SquareCache squareCache)
{
    foreach (var number in numbers)
    {
        var square = squareCache.GetValue(number);
        Console.WriteLine($"{number} * {number} = {square}");
    }
}

PrintSquares still looks good. But I’m not that satisfied with SquareCache. Let’s see what we can do to the cache implementation.

Composition

We can get rid of the class hierarchy if we use composition. That means, we have to define an appropriate interface and pass an object that implements that interface as a constructor parameter - that pattern is known as constructor dependency injection.

For our example, I define the interface Executor - great name, right? - and add a constructor requiring an Executor instance to the Cache class:

public interface Executor<TKey, TValue>
{
    TValue Execute(TKey key);
}

public class Cache<TKey, TValue> where TKey : notnull
{
    readonly Executor<TKey, TValue> Executor;
    readonly Dictionary<TKey, TValue> entries = new Dictionary<TKey, TValue>();

    public Cache(Executor<TKey, TValue> executor)
    {
        Executor = executor;
    }

    public TValue GetValue(TKey key)
    {
        if (!entries.TryGetValue(key, out TValue value))
        {
            value = Executor.Execute(key);
            entries.Add(key, value);
        }
        return value;
    }
}

The nice thing about this approach is, that you can implement the Executor interface wherever it fits best. You’re not forced into a class hierarchy.

First, let’s look at PrintSquares again. Now, we don’t have an explicit SquareCache class. PrintSquares has to deal with a more general Cache<int, int> parameter:

public static void PrintSquares(IEnumerable<int> numbers, Cache<int, int> squareCache)
{
    foreach (var number in numbers)
    {
        var square = squareCache.GetValue(number);
        Console.WriteLine($"{number} * {number} = {square}");
    }
}

In some situations, that might be a drawback. However, it’s simply a consequence of the gained flexibility: you don’t know how squareCache will be composed at compile-time, that happens at run-time. That’s why you call it object composition - in contrast to class inheritance.

For our example, I simply have a new class called SquareExecutor that implements Executor:

public class SquareExecutor : Executor<int, int>
{
    public int Execute(int number) => CalculateSquare(number);
}

Now, you have to compose the cache before you can use it:

var squareCache = new Cache<int, int>(new SquareExecutor());
PrintSquares(numbers, squareCache);

We’ll talk about class inheritance vs. object composition in many more posts to come. For now, I want to share with you a quote from Design Patterns by the “Gang of Four”:

Favor object composition over class inheritance.

That’s it for today’s post. There are no more ways I can think of how you could implement a cache in an OO langue. Do you know some more? But C# isn’t a pure OO langue, there’s an ever-growing functional influence. So … in the next post we’ll have some more fun with caching. But then, we’ll make things more functional.

Did you have some fun? I’m amazed by how many different things you can talk about with such a small example. As professionals, should we invest more of our time to talk about code?

Option Type in C#

2019-11-19T05:00:00-06:00

If you know F# (or Haskell, OCaml, …), you know the Option type (or Maybe type). If you’re not familiar with the Option type, you might want to have a look at the fantastic introduction by Scott Wlaschin.

If you know the Option type, you might be missing it when you’re programming in C# … I do. But I’m not the only one. There are multiple Option type implementations for C# on GitHub. The most popular implementation is probably language-ext, but it’s more than just an Option type (as the name implies).

With this blog post, my goal is to make you miss the Option type - even if you didn’t know the Option type before.

The Option Type

Let’s jump right into it and have a look at an implementation of the Option type:

public struct Option<T>
{
    public static Option<T> None => default;
    public static Option<T> Some(T value) => new Option<T>(value);

    readonly bool isSome;
    readonly T value;

    Option(T value)
    {
        this.value = value;
        isSome = this.value is { };
    }

    public bool IsSome(out T value)
    {
        value = this.value;
        return isSome;
    }
}

So, an Option can either be None or Some. If the Option is None, it doesn’t have an associated value. If the Option is Some, it does have an associated value. Basically, Option makes the absence of a value explicit.

Remark to Some(null): I don’t allow Some(null). If you pass null anyway, I treat it as None. I think that’s the preferable approach for most practical applications. However, that can be an issue if null has a meaning in your code base - the monad laws might not hold. But I won’t go into more details in this post.

If you want to know if an Option is None or Some, you have to call IsSome. That way, you can’t accidentally access the value of None.

if (option.IsSome(out var value))
{
    //option is Some(value)
}
else
{
    //option is None
}

So … no more NullReferenceExceptions?
Yup!
That’s great … but, isn’t there something called nullable reference types?

Prior to C# 8.0, the avoidance of NullReferenceExceptions was a major selling point for the Option type. But that’s not true anymore. The C# team chose nullable reference types over Options. In that spirit, if all you want is to avoid NullReferenceExceptions, don’t use Options, use nullable reference types instead.

But we can actually use nullable reference types to improve the Option implementation:

public struct Option<T> where T : notnull
{
    public static Option<T> None => default;
    public static Option<T> Some(T value) => new Option<T>(value);

    readonly bool isSome;
    readonly T value;

    Option(T value)
    {
        this.value = value;
        isSome = this.value is { };
    }

    public bool IsSome([MaybeNullWhen(false)]out T value)
    {
        value = this.value;
        return isSome;
    }
}

With the added type constraint T : notnull, it’s made explicit that I don’t allow null - before, it was only a convention. With the attribute MaybeNullWhen(false), you get a compiler warning if you use the out parameter without checking it for null when IsSome returns false.

There’s More to the Option Type

The Option type isn’t just a “nicer” null. But to gain its full power, it needs some more methods - I’ll show to you some of the most important. I put all the following methods in a static class called OptionExtensions. I omit the class definition for all but the first method.

Let’s start with Match:

public static class OptionExtensions
{
    public static U Match<T, U>(this Option<T> option,
        Func<T, U> onIsSome, Func<U> onIsNone) where T : notnull =>
            option.IsSome(out var value) ? onIsSome(value) : onIsNone();
}

Match is the preferred way to work with the value of an Option. You have to provide two Func. onIsSome is called if option is Some, onIsNone is called if option is None. Both have to return the same type. As you can see, Match returns the result of the called Func.

Match is preferred to IsSome because you can’t miss a case. You always have to provide onIsSome and onIsNone. IsSome, however, might feel more natural to use if you don’t have a value to return but want to do some side effects.

Next, we have Bind and Map:

public static Option<U> Bind<T, U>(this Option<T> option, Func<T, Option<U>> binder)
    where T : notnull where U : notnull =>
        option.Match(
            onIsSome: binder,
            onIsNone: () => Option<U>.None);

public static Option<U> Map<T, U>(this Option<T> option, Func<T, U> mapper)
    where T : notnull where U : notnull =>
        option.Bind(
            value => Option<U>.Some(mapper(value)));

Both methods transform an Option to another Option.

Let’s start with Bind. If option is Some(value), Bind calls binder with the value of option as parameter and returns the result. The result of binder is itself an Option. If option is None, Bind returns None - binder doesn’t get called.

Map is similar to Bind - that’s why it actually calls Bind. But the result of mapper gets wrapped with an Option before it’s returned by Map.

I don’t go into more detail. It’ll make more sense once we have some examples.

There are two more methods I want to show to you. We need them for the following examples:

public static Option<T> Filter<T>(this Option<T> option, Predicate<T> predicate)
    where T : notnull =>
        option.Bind(
            value => predicate(value) ? option : Option<T>.None);

public static T DefaultValue<T>(this Option<T> option, T defaultValue)
    where T : notnull =>
        option.Match(
            onIsSome: value => value,
            onIsNone: () => defaultValue);

Without much explanation:
Filter checks if the value of option satisfies predicate. If it does, option is returned unchanged. Else, Filter returns None.
DefaultValue returns the value of option if it’s Some. Else, it returns defaultValue.

I guess it’s time for some examples.

The Power of Bind

I only touch the surface here. If you want to know more about The Power of Composition or Railway Oriented Programming, check out the wonderful site F# for fun and profit by Scott Wlaschin.

Do you have code where the output of the first method is the input to the second method? And the output of the second method is the input to the third method. And … so on. Do your methods possibly return null? Then, your code might look something like this:

var result1 = Step1();
if (result1 != null)
{
    var result2 = Step2(result1);
    if (result2 != null)
    {
        var result3 = Step3(result2);
        //and so on ...
    }
}

A lot of repetitive boiler plate code, don’t you think? What if your methods returned an Option instead of something that might be null? Then, your methods would look like this:

static Option<ResultStep1> Step1()
{ /* return Some(value) or None */ }

static Option<ResultStep2> Step2(ResultStep1 input)
{ /* return Some(value) or None */ }

static Option<ResultStep3> Step3(ResultStep2 input)
{ /* return Some(value) or None */ }

Now, it’s time to unleash the awesome power of Bind! Let’s see how we can get rid of all that boiler plate code:

var result =
    Step1()
    .Bind(Step2)
    .Bind(Step3);

I don’t know about you, but I love how easy it is to stitch together methods using Bind. The first method that returns None stops the execution and None becomes the final result. Just like “short-circuiting” with conditional logical operators in C#.

The Missing LINQ

There’s another area where I like to use Options: data access. Let’s say we have the following repository:

interface Flights
{
    IEnumerable<Flight> GetFlights(string airline);
    Flight? GetFlight(string number);
}

Now, I want to get all the free seats of an airline where the departure time is between one and five hours in the future:

static bool CheckDepartureTime(Flight flight)
{
    var now = DateTime.Now;
    return flight.Departure >= now.AddHours(1) && flight.Departure <= now.AddHours(5);
}

static int GetFreeSeatsOfAirline(Flights flights, string airline) =>
    flights.GetFlights(airline)
    .Where(CheckDepartureTime)
    .Sum(_ => _.FreeSeats);

Ok, GetFreeSeatsOfAirline is compact and straight forward. Now, let’s suppose we want to get the free seats of a specific flight, but only if the flight satisfies CheckDepartureTime (don’t think about the usefulness of that constraint too much):

static int GetFreeSeatsOfFlight(Flights flights, string number)
{
    var flight = flights.GetFlight(number);
    return flight != null && CheckDepartureTime(flight) ? flight.FreeSeats : 0;
}

GetFreeSeatsOfFlight does pretty much the same as GetFreeSeatsOfAirline. Yet, it looks quite different. That bothers me. If two pieces of code do pretty much the same, I expect them to look pretty much the same.

Let’s change the repository method GetFlight to return Option<Flight> instead of Flight?:

interface Flights
{
    IEnumerable<Flight> GetFlights(string airline);
    Option<Flight> GetFlight(string number);
}

Now, we can implement GetFreeSeatsOfFlight like this (I included GetFreeSeatsOfAirline for comparison):

static int GetFreeSeatsOfFlight(Flights flights, string number) =>
    flights.GetFlight(number)
    .Filter(CheckDepartureTime)
    .Map(_ => _.FreeSeats).DefaultValue(0);

static int GetFreeSeatsOfAirline(Flights flights, string airline) =>
    flights.GetFlights(airline)
    .Where(CheckDepartureTime)
    .Sum(_ => _.FreeSeats);

I’d say the two methods look pretty much the same. And that comes with a big advantage: Because they do pretty much the same, chances are high that if you have to change one of the methods, you also have to change the other method. Since their structure is similar, it’s easy to apply the same change to both methods. Basically, if you understand one method, you automatically understand the other method.

I sometimes describe the Option type as “LINQ for single values”. There are scenarios where LINQ doesn’t feel complete without the Option type.

Implementation

You can find an Option type implementation in my GitHub repository functional-extensions.

Have I achieved my goal? Do you miss the Option type in C#? Or is it some functional shenanigans nobody needs in an object-oriented language?

Clean Code - Part 2

2019-11-12T05:00:00-06:00

My last post was an introduction to Robert Martin’s Clean Code. In this post, I’ll give you some examples of clean code. But it’s not meant to be a summary of Clean Code. I only want to give you an idea about what clean code looks like. I already said it in my last post and I’m going to say it again: read the book! You’ll find a lot of aspects in it I’m not even mentioning here.

Names

Names have to be meaningful. Good names make your intent obvious. Be it the name of a variable, a method, a class or a project. Let’s have a look at the naming of a variable:

int dsc;

Do you have any idea what dsc stands for? I don’t. Even Wikipedia isn’t sure. I think it’s a good idea to make the name more meaningful:

int daysSinceCreation;

Did you guess dsc was supposed to mean days since creation? Probably not. That’s why you should go for a more descriptive name - take the guessing out. The same’s true when you’re naming methods, classes or projects. Put yourself in the reader’s position.

But longer names aren’t automatically better. Unnecessary long names can have a negative effect and blur your intent. Here’s a particularly wordy example:

public class SubscriberIdList
{
    public void AddSubscriberIdToList(Guid subscriberIdToAdd)
    {
        //...
    }

    public void RemoveSubscriberIdFromList(Guid subscriberIdToRemove)
    {
        //...
    }

    public void RemoveAllSubscriberIdsFromList()
    {
        //...
    }
}

You can see the good intention of the author. But it’s too much. Most of the words are nothing but noise. A meaningful version might look something like this:

public class Subscribers
{
    public void Add(Guid id)
    {
        //...
    }

    public void Remove(Guid id)
    {
        //...
    }

    public void Clear()
    {
        //...
    }
}

No unnecessary distractions. Clean code is direct and tells you exactly what it does.

Methods

Methods should do one and only one thing. If a method does more than one thing you should split it up into two or more methods. How do you know if a method does only one thing? Well … that’s up to us developers to decide. One hint is if you can explain what the method does without using “and”.

Methods should be small. Do you write methods with more than 100 lines? That’s too long! Even 50 lines is too long. But how many lines is ok? It depends. A reader should be able to understand and reason about the entire method. So to say, the method has to fit into one’s head. There isn’t a fixed limit. But if you can keep it under 10 or 15 lines, that’s great.

Methods should operate on a consistent level of abstraction. Don’t deal with high-level concerns and low-level concerns in one method. The following method operates on an inconsistent level of abstraction:

public void CreateInvoice()
{
    LoadItems();
    CalculateNet();

    if(!IsVATExempt)
    {
        var rate = GetVATRate();
        this.sum +=
            Math.Round(sum * rate, decimals: 2, MidpointRounding.AwayFromZero);
    }

    Export();
}

It doesn’t look right. On the one hand, there are high-level abstractions like LoadItems or Export. On the other hand, there’s some very low-level code dealing with rounding stuff like rounding precision. Let’s improve the method by bringing it to a more consistent level of abstraction:

public void CreateInvoice()
{
    LoadItems();
    CalculateNet();
    AddVAT();
    Export();
}

void AddVAT()
{
    if (!IsVATExempt)
    {
        var rate = GetVATRate();
        this.sum +=
            Math.Round(sum * rate, decimals: 2, MidpointRounding.AwayFromZero);
    }
}

Now CreateInvoice looks way better. All steps are on a similar level of abstraction. The new method AddVAT deals with the low-level concerns. But there’s still room for improvement:

public void CreateInvoice()
{
    LoadItems();
    Calculate();
    Export();
}

void Calculate()
{
    CalculateNet();
    AddVAT();
}

void AddVAT()
{
    if (!IsVATExempt)
    {
        var rate = GetVATRate();
        this.sum +=
            Math.Round(sum * rate, decimals: 2, MidpointRounding.AwayFromZero);
    }
}

Now CreateInvoice truly operates on a consistent, high level of abstraction. Calculate operates one level of abstraction below CreateInvoice and AddVAT operates on the lowest level of abstraction. The example also shows how a consistent level of abstraction automatically leads to small methods that are doing only one thing.

Classes

Classes should have a single responsibility. Or as Uncle Bob puts it

… a class or module should have one, and only one, reason to change.

Like with methods, it’s not always easy to define what’s a single responsibility. Again, a hint is if you can describe what the class does without using “and”. If you have to use “and”, your class has probably more than one reason to change.

Classes should be small. Do you have to permanently scroll up and down to understand a class? Then, your class is too large. You can’t reason about a class if it doesn’t fit into your head. Sticking to the Single Responsibility Principle is a major step to reducing the size of your classes.

We’ll talk about classes in more detail in another post.

Comments

The most important quote about comments is

Comment do not make up for bad code.

And that’s not the job of comments. As a developer, you have to express your intent in code. Everything that can be expressed in code has to be expressed in code. Comments are for those cases were code isn’t enough. Code can only express what is done, but it can’t express why something is done. If the why is of importance to the reader, adding a comment is a good idea.

But let’s have a look at some bad comments. Here’s a perfect example of an unnecessary comment:

i++;    //add one to i

That comment is nothing but noise. There’s no value to the reader. Want to have some more noise? Ok, let’s take the wordy method from before and make it worse:

/// <summary>
/// List of subscriber identifiers.
/// </summary>
public class SubscriberIdList
{
    /// <summary>
    /// Adds a subscriber identifier to the list of subscriber identifiers.
    /// </summary>
    /// <param name="subscriberIdToAdd">The identifier to add to the list of
    /// subscriber identifiers.</param>
    public void AddSubsriberIdToList(Guid subscriberIdToAdd)
    {
        //...
    }

    /// <summary>
    /// Removes a subscriber identifier from the list of subscriber identifiers.
    /// </summary>
    /// <param name="subscriberIdToRemove">The subscriber identifier to remove
    /// from the list of subscriber identifiers.</param>
    public void RemoveSubscriberIdFromList(Guid subscriberIdToRemove)
    {
        //...
    }

    /// <summary>
    /// Removes all subscriber identifiers from the list of subscriber identifiers.
    /// </summary>
    public void RemoveAllSubscriberIdsFromList()
    {
        //...
    }
}

Does anyone think those comments are valuable to the reader?

Up until now, we’ve looked at examples of good and bade code. But how do you actually write clean code? We’ve already seen how to write clean code when we were talking about methods: You start with working code and refine it into clean code. It’s hard to write clean code from scratch. Clean code isn’t obvious, it emerges once you know how to solve a problem. If you want to have clean code (or quality code in a broader sense), you have to put additional effort into your code.

The Boy Scout Rule

How much effort? As professionals, we have to manage our time responsibly. There’s a danger to the commitment to clean code. You can get lost in meaningless details. Refining your code for hours without adding real value. But that’s part of our job. It’s up to us to find the sweet spot between extra time spent now and long-term benefits.

The Boy Scout Rule might help:

Leave the campground cleaner than you found it.

It’s talking about the campground, not the entire forest. Don’t clean up code without need. We all learn and get better over time. I constantly cringe about the code I wrote a couple of years or maybe only several month ago. But that’s no excuse to spend all your time on improving old code. Do the best you can with the code you’re writing right now. Eventually, you’ll have to modify some of your old code anyway - be it to fix a bug or to add a new feature. That’s the time when you put some extra effort into. You don’t just fix the bug or cram the new feature into the existing mess - you also clean up the campground around it.

Secondly, it says cleaner. It doesn’t say you have to fix everything. Only make sure that the code is in a better condition now than when you found it.

Are you an author? Do you put your readers first? Or is it their problem if they don’t understand your code. Tell us in the comments.

Clean Code

2019-11-05T05:00:00-06:00

This post is about the wonderful book Clean Code by Robert Martin. Clean Code changed the way I write code. If you have a look at the code I produced over the last couple of years, you can tell the code before I read Clean Code from the code after I read Clean Code. It’s that big a difference.

This post isn’t a summary of Clean Code. It’s about the principle behind Clean Code: Code is meant to be understood by humans.

You might think, “Wait … the purpose of code is to be executed by a machine.” That’s obviously true. But if it were about the machines, there would be no need for the fancy programming languages we use. The computer doesn’t care about classes, lambda expressions or generics. It doesn’t care about how you name methods or variables. It doesn’t care if you split your code into multiple small files or if you stuff everything into one enormous file. In fact, the computer doesn’t care about most of the things we spend our time pondering about. That’s why we have to compile the code we write. The compiler gets rid of all the bells and whistles we’ve put so much effort into, when it brings the code into a format the computer does care about. Well then, why do we spend so much time caring about things that get erased during compilation anyway? Because it’s not about machines, it’s about humans.

I got that without reading Clean Code. We have high-level programming languages to make writing code easier. What I didn’t get - or didn’t care enough about - is that I’m not alone. Enterprise software development is a team sport. It’s not sufficient that I understand the code I write, everyone on the team should able to understand the code I write. Of course, I can’t guarantee that everyone will understand the code I write, but it’s my duty to make it as easy for them as reasonably possible.

A quote from the book sums it up perfectly:

We are authors. And one thing about authors is that they have readers.

Good authors care about their readers. Clean code is easy to read, easy to reason about and easy to change.

The Subtitle Tells You More

Let’s have a look at the subtitle: A Handbook of Agile Software Craftsmanship. There are two important aspects.

Agile: Agile software development means constantly changing code. Before you can change code, you have to understand it first. We’re talking about enterprise software. That means there is a team of developers that has to deal with a large code base. In such a scenario it happens all the time that the one who has to modify a piece of code isn’t the one who initially wrote the code. Enterprise software is long-lived. The one who wrote it might have already left the company. That’s why clean code is an absolute must for enterprise software. If your code base is unintelligible, you’re in big trouble.

Software Craftsmanship: I’ll talk about software craftsmanship in another post. For now, just think of it as the difference between being satisfied with working code and striving for quality code. It means that you are willing to put some extra effort into your working code and turn it into clean code.

What’s to Gain?

Do you want to sell the idea of clean code to someone? Ok, here are two more selling points:

Clean code is fast to change: I already said that clean code is easy to understand and therefore easy to change. But it’s also fast to change. That’s important when you have to compete in the marketplace. Every new feature has to be integrated into the current system. You can do that a lot faster if you understand the current system.

Clean code tends to have less bugs: Did you ever change code you didn’t quite understand? I did. And let me tell you, that’s not a good idea. If you don’t understand the code you change, it’s only a matter of luck if you unintentionally break something else or not.
There’s another important aspect. If your code is easy to understand, you can reason about it with team members without explaining what the hell your code is even doing first. Talking about your code with others is a great way to reduce bugs.

Conclusion

Clean code cares about its readers. Clean code tells you what it does without hidden surprises. It’s pleasant to read and easy to change. In the next post I’ll give you some examples of clean code. We’ll talk about names, methods, classes and comments. And about how you turn working code into clean code.

A Final Thought

If you haven’t read Clean Code yet, read it!

How important is clean code? Essential for success? Or is working code all you need? Tell me in the comments.

Quality Matters

2019-10-29T06:00:00-05:00

Quality is the foundation for long-term success.

I’m convinced that’s true. In this post I talk about why quality matters and what’s the cost of neglecting it.

Let me start with an obvious property of quality code: it works. This blog is about professional software development. Working software is a must - but by no means easy to achieve. However, working software isn’t enough. Quality software is more than just working software. Though, quality helps us to build working software in the first place and to keep it working despite all modifications and extensions along the way.

Which Quality I’m Talking About

Different stakeholders have something very different in mind when we talk about quality. To users a quality application is easy to use, robust and quick. To project managers a quality project is on budget and on time. All the different views on quality are legitimate and important - and they are all affected by the code we write.

This blog is for enterprise software developers - when I talk about quality, I mean the quality of the code we write and the quality of the process we use to write that code. However, code quality is at the basis of the other kinds of quality:

User experience is a result of the code we write.
Performance is a result of the code we write.
Security is a result of the code we write.
Bugs are a result of the code we write.
Being able to meet project plans depends on how we write code.
Being able to quickly respond to changes in the marketplace depends on how we write code.
The success of the company depends on how we write code.
Having fun doing our job depends on how we write code.
How easy it is for new developers to join the team depends on how we write code.

Mark Seemann talks about the difference between software quality and code quality in one of his blog posts.

Why Quality Is Important for Enterprise Software

It’s obvious that the code we write determines the functionality of our application. But that’s not an argument for the importance of code quality yet.

So … Is it possible to be successful with a crappy code base? Sure!
But … Is it possible to be successful in the long run in a constantly changing environment with a crappy code base? I doubt it.

There’s a hilarious video by Robert Martin aka Uncle Bob where he talks about the importance of good code and how bad code can destroy an initially successful company. However, the importance of quality does depend on the type of your application. Let’s say you are writing a promotional app for an event with a fixed date. The day the event happens also marks the end of your project. Mission accomplished - let’s move on to the next project. In such a scenario quality doesn’t matter that much - but even if your project only lasts a few weeks you can start feeling the pain of bad code.

This blog, however, is about enterprise software development. The characteristics of enterprise software are the reason why quality is of such importance:

Enterprise software is long-lived.
The requirements are constantly changing.
You are working on a team.
Bugs can be costly.
You have to compete in the marketplace.

What’s Quality?

Let’s say your software is in a working state called A. Now, you have to implement a new feature or fix a bug. Let’s call the new working state including the added feature or bug fix B. That means, you have to transform your software from some working state A to another working state B.

Quality isn’t about the working states A or B, it’s about the transformation. If the transformation from A to B is easy, your code is of high quality. If the transformation from A to B is hard, your code is of low quality. That’s my definition of quality: High quality code is easy to change.

What makes the transformation easy? There are two aspects.
First, the state A matters. If your code is a mess, it’s hard to transform it to B. If your code is difficult to understand, it’s hard to transform it to B. If you don’t have any tests, it’s hard to transform it to B …
Second, the process matters. How you write and test code matters. The programming languages, frameworks and tools you use matter. How the team members work together matters. Project management matters …

There’s No Free Lunch

Quality comes with a cost. You have to put additional effort into your code. You’re not finished once your code works, you have to do a little more and turn it into quality code. But is it worth the effort? Yes. It pays off in the long run. There’s a great blog post by Martin Fowler about it. I really recommend reading it.

How does quality pay off?

If it’s hard to change your software, then …
… it’s hard to add new features.
… it takes a long time to add new features.
… bugs are more likely.
… bugs are hard to fix.
… it takes a long time to fix bugs.

If it’s easy to change your software, then …
… it’s easy to add new features.
… you can add new features quickly.
… bugs are less likely.
… bugs are easy to fix.
… you can fix bugs quickly.

If your goal is long-term success, you have to invest in quality.

This post together with the post about enterprise software is the foundation of my blog. It’s all about writing high quality enterprise software.

Are you convinced of the importance of quality? Or is working software all that matters? Let’s discus it in the comments.

How to Implement List Properties. It’s Not as Simple as It Sounds.

2019-10-22T06:00:00-05:00

In this entire post I talk about the implementation of a single property of type List<T> … that’s why I love software development.

I want to use a blog post by Mark Seemann as starting point for my post (btw, if you aren’t a regular reader of Mark’s blog already, you should definitely become one). So, you have to read Mark’s post first. I wait here …

… great, you’re back! In his post Mark writes:

The problem is aliasing. While named differently, subscribers and sut.Data.Subscribers is the same object.

However, it’s only a problem because subscribers and sut.Data.Subscribers point to the same mutable object. Mark mentions that in Fixing the problem. In this post I want to work on the implementation of StatusPolicyData. Maybe there’s a way to prevent the unexpected behavior from happening in the first place.

An Iterative Approach

Let’s have a closer look at StatusPolicyData. I guess it looks something like this:

public class StatusPolicyData
{
    public int UnitId { get; set; }
    public List<Guid> Subscribers { get; set; }
}

That’s how a lot of C# code looks like. Basically, the language is encouraging you to write code that way. If you want anything else you have to put additional effort into it (i.e. do more typing).
Well then, let’s put some effort into it. First, I enable nullable reference types (see last post) to prevent NullReferenceExceptions. Now, StatusPolicyData hast to look like this to get rid of all compiler warnings:

public class StatusPolicyData
{
    public int UnitId { get; set; }
    public List<Guid> Subscribers { get; set; } = new List<Guid>();
}

What’s next? Maybe it’s time to get a little help and install the Microsoft.CodeAnalysis.FxCopAnalyzers NuGet package. Once you’ve installed the analyzer you get the warning CA2227: Collection properties should be read only. I just make the warning go away:

public class StatusPolicyData
{
    public int UnitId { get; set; }
    public List<Guid> Subscribers { get; } = new List<Guid>();
}

Removing the setter is a breaking change, though. Let’s have a look at the original code from False negative again:

var subscribers = new List<Guid> { /* some Guid */ };
var sut = new StatusPolicy
{
    Data = new StatusPolicyData
    {
        UnitId = 123,
        Subscribers = subscribers
    }
};

With the removed setter we have to initialize StatusPolicyData like this:

var subscribers = new List<Guid> { /* some Guid */ };
var data = new StatusPolicyData
{
    UnitId = 123
};
data.Subscribers.AddRange(subscribers);
var sut = new StatusPolicy
{
    Data = data
};

That doesn’t improve readability. But the good news is, the change is sufficient to make HandleObserveUnitStatusStartsSaga in Mark’s post fail as expected. subscribers and sut.Data.Subscribers don’t point to the same object anymore. End of the story? Of course not! Let’s see what we can do to make it more readable. Why not add a constructor parameter?

public class StatusPolicyData
{
    public StatusPolicyData(List<Guid> subscribers)
    {
        Subscribers = subscribers;
    }

    public int UnitId { get; set; }
    public List<Guid> Subscribers { get; }
}

Now, we can initialize StatusPolicyData like this:

var subscribers = new List<Guid> { /* some Guid */ };
var sut = new StatusPolicy
{
    Data = new StatusPolicyData(
        subscribers: subscribers)
    {
        UnitId = 123
    }
};

That looks way better. Unfortunately, HandleObserveUnitStatusStartsSaga doesn’t fail with the last change to StatusPolicyData - so we’re back to a false negative. That’s not surprising. subscribers and sut.Data.Subscribers point to the same object all again.
In Fixing the problem, Mark edits the unit test HandleObserveUnitStatusStartsSaga. He defines subscribers as an IEnumerable and creates a new list by calling ToList() before assigning it to the property Subscribers. Here’s Mark’s code:

IEnumerable<Guid> subscribers = new[] { /* some Guid */ };
var sut = new StatusPolicy
{
    Data = new StatusPolicyData
    {
        UnitId = 123,
        Subscribers = subscribers.ToList()
    }
};

Why not move the fix into the implementation of StatusPolicyData? By doing that, we make it impossible to run into the same issue again - the next time it might as well cause some unexpected behavior in production:

public class StatusPolicyData
{
    public StatusPolicyData(IEnumerable<Guid> subscribers)
    {
        Subscribers = subscribers.ToList();
    }

    public int UnitId { get; set; }
    public List<Guid> Subscribers { get; }
}

With the above implementation of StatusPolicyData, the initial version of HandleObserveUnitStatusStartsSaga from False negative fails as expected. There’s only one more thing I’d like to change. In order to make StatusPolicyData more pleasant to use, I make the constructor parameter optional:

public class StatusPolicyData
{
    public StatusPolicyData(IEnumerable<Guid>? subscribers = null)
    {
        Subscribers = subscribers?.ToList() ?? new List<Guid>();
    }

    public int UnitId { get; set; }
    public List<Guid> Subscribers { get; }
}

That’s it. That’s a possible implementation of StatusPolicyData to prevent the unexpected behavior from happening:

Make the property read-only.
Have an (optional) constructor parameter of type IEnumerable.
Copy the elements to a new list instance in the constructor.

Do You Want to Go the Extra Mile?

Ok, there’s another issue we can work on. Have a look at the following test code (I’m using MSTest):

var subscribers = new List<Guid> { /* some Guid */ };
var sut = new StatusPolicyData(
    subscribers: subscribers)
{
    UnitId = 123
};

PrintIds(sut.Subscribers);

CollectionAssert.AreEqual(subscribers, sut.Subscribers);

Will the test succeed? It’s impossible to tell. It depends on the implementation of PrintIds. What if PrintIds is implemented like this:

void PrintIds(List<Guid> ids)
{
    ids.Clear(); //Enter the Devil ;-)
}

Obviously, the test will fail. Once again, the problem is aliasing. sut.Subscribers and ids point to the same mutable object.

Don’t Expose Mutable Objects

To make the unintended behavior impossible, we have to encapsulate the mutable list and only expose an immutable list. But we still need to be able to modify the list. Therefore, we have to add modification methods to StatusPolicyData:

public class StatusPolicyData
{
    readonly List<Guid> subscribers;

    public StatusPolicyData(IEnumerable<Guid>? subscribers = null)
    {
        this.subscribers = subscribers?.ToList() ?? new List<Guid>();
        Subscribers = this.subscribers.AsReadOnly();
    }

    public int UnitId { get; set; }
    public ReadOnlyCollection<Guid> Subscribers { get; }

    public void AddSubscriber(Guid subscriber) =>
        subscribers.Add(subscriber);

    public void RemoveSubscriber(Guid subscriber) =>
        subscribers.Remove(subscriber);

    public void ClearSubscribers() =>
        subscribers.Clear();
}

Given the above implementation, we have to modify the test code. You can’t just pass sut.Subscribers to PrintIds, you have to pass sut.Subscribers.ToList():

var subscribers = new List<Guid> { /* some Guid */ };
var sut = new StatusPolicyData(
    subscribers: subscribers)
{
    UnitId = 123
};

PrintIds(sut.Subscribers.ToList());

CollectionAssert.AreEqual(subscribers, sut.Subscribers);

Now the test succeeds independently from the implementation of PrintIds - if PrintIds doesn’t throw an exception. That makes your code way easier to understand. You don’t have to look up the implementations of the methods you are calling to make sure they don’t modify the lists you are passing.

There’s another benefit to having modification methods: you can implement some form of change notification (e.g. raise an event).

Immutability

As we’ve seen, mutability can cause some unexpected behavior. Do you like your code to behave as expected? Then I suggest to go for immutability - only fallback to mutability if necessary. Here’s what an immutable version of StatusPolicyData looks like:

public class StatusPolicyData
{
    public StatusPolicyData(
        int unitId,
        IEnumerable<Guid>? subscribers = null)
    {
        UnitId = unitId;
        Subscribers = (subscribers?.ToList() ?? new List<Guid>()).AsReadOnly();
    }

    public int UnitId { get; }
    public ReadOnlyCollection<Guid> Subscribers { get; }

    public StatusPolicyData AddSubscriber(Guid subscriber) =>
        new StatusPolicyData(UnitId, Subscribers.Append(subscriber));

    public StatusPolicyData RemoveSubscriber(Guid subscriber) =>
        new StatusPolicyData(UnitId, Subscribers.Except(new[] { subscriber }));

    public StatusPolicyData ClearSubscribers() =>
        new StatusPolicyData(UnitId);
}

What Would It Look Like in F#?

I’m glad you asked. When we’re talking about immutability, it’s only logical to consider using a language where immutability is the default case. Here’s an F# version of StatusPolicyData:

type StatusPolicyData =
    { UnitId : int
      Subscribers : Guid list }

module StatusPolicyData =

    let addSubscriber subscriber (statusPolicyData : StatusPolicyData) =
        { statusPolicyData with
            Subscribers = subscriber :: statusPolicyData.Subscribers }

    let removeSubscriber subscriber (statusPolicyData : StatusPolicyData) =
        { statusPolicyData with
            Subscribers = List.except subscriber statusPolicyData.Subscribers }

    let clearSubscribers (statusPolicyData : StatusPolicyData) =
        { statusPolicyData with
            Subscribers = [] }

What do you think about the different implementations? Is immutability the way to go? Or is the simplest implementation also the best one? Tell me in the comments.

C# 8.0 Nullable Reference Types: The End of the NullReferenceException?

2019-10-15T06:00:00-05:00

C# 8.0 introduced a major new feature: nullable reference types. In this post, I want to answer the question if that’s the end of the pesky NullReferenceException.

Pre C# 8.0: How to Deal with Null

Before C# 8.0 there were basically two ways of dealing with null. A defensive approach and one that requires discipline.

Null Checks

If you can’t be sure if something is null, there’s only one responsible thing to do: check if it’s null (a.k.a. being defensive). There’s just one problem with the C# type system, you can never be sure. So, as a professional programmer you will write code that looks something like this:

void ExecuteWorkflow()
{
    var resultStep1 = DoStep1();
    if (resultStep1 != null)
    {
        var resultStep2 = DoStep2(resultStep1);
        if (resultStep2 != null)
        {
            //...
        }
        else
        {
            //handle resultStep2 is null
        }
    }
    else
    {
        //handle resultStep1 is null
    }
}

Or like this:

void DoImportantWork(Component component, Data data)
{
    if (component is null) throw new ArgumentNullException(nameof(component));
    if (data is null) throw new ArgumentNullException(nameof(data));

    //do important work
}

Not particularly pretty. Those null checks get sprinkled all over your code base - causing a lot of noise.

Convention and Discipline

You can get around some null checks by applying a simple convention: Don’t return null. Don’t pass null. Easy, right? Well … it can work in areas where you’ve got full control over the executed code and when every programmer on the team is on the same page. However, in a reasonably sized business application you’ll eventually have to use some third-party frameworks. Do these frameworks return null? Once again, if you can’t be sure you have to do null checks.

There’s another catch to that approach. What do you do when you don’t have anything meaningful to return? You can’t return null, that violates the convention.
Throw an exception? At least you are trading a cryptic NullReferenceException for a more specific exception. That’s some improvement. But you can’t force the caller of the method to handle your exception (there’s no such thing as checked exceptions in C#).
Return a result code and have an additional out parameter? Again, that’s some improvement over returning null. But I wouldn’t call it pretty. And you can’t ensure that the caller of the method only dereferences the out parameter in the case of success.
Return some special case empty object? That’s the preferable approach. In the case of something like a list it’s straightforward to do, return an empty list instead of null. But it’s not always that easy to construct a special case empty object for an arbitrary type. (Or is it? We’ll talk about that in an upcoming post again.)

C# 8.0 to The Rescue

Null checks and conventions both have one major issue - they are error prone. It’s way too easy to make a mistake. Wouldn’t it be nice if the compiler made it impossible to mess up? That’s what C# 8.0 nullable reference types are for. If you’re looking for an introduction check out the presentation from Mads Torgerson. In this post I’ll focus on the things you have to watch out for with the new feature.

Basically, with nullable reference types enabled reference types aren’t allowed to be null. If you want that a reference type can be null, you have to add a question mark to the type definition:

string a = "can't be null";
string? b = null; //can be null

So, as long as you are dealing with non-nullable reference types, there’s no need for null checks anymore. But what if you want to include null because there is no meaningful value to assign? Back to null checks? Yes, but the compiler makes sure you don’t miss a null check. If you dereference a variable without checking it first, you get a compiler warning. That’s awesome! But there’s something you need to be aware of …

… It’s Not a Silver Bullet

To be clear, I love the new feature! I see a big potential to improve overall code quality and I want to say thank you to everyone who’s been involved. Nevertheless, I’d like to talk about some things you should keep in mind.

You only get warnings: If you do something the compiler deems unsafe, you get a compile-time warning, not an error. You can still build and execute your code (and enjoy your NullReferenceExceptions). I absolutely understand why they decided to generate compiler warnings instead of errors - enabling nullable reference types for an existing code base would else be virtually impossible. But we all know the problem with warnings, they are way too easy to ignore. The question is, how many warnings do you get when you build your solution? Zero? That’s great! You’ll notice every new warning and I’m sure you’ll get rid of it as soon as possible. But what if your build already produces hundreds of even thousands of warnings? I’ve seen that (I need to stress that that’s not how it’s supposed to be). In such a scenario warnings have little impact (yes, the squiggly lines while coding are still a great improvement).
For green field projects, you should consider enabling the TreatWarningsAsErrors compiler flag. If that’s not an option, you should think about treating some (or all) of the nullable reference types related warnings as errors. There’s a blog post by Jiří Činčura talking about that.

You can’t stop callers from passing null: That’s a result of the fact that you get only a warning when you are passing null where you shouldn’t. Now, what does that mean? Back to null checks? Yes and no. For public APIs, I’d still add null checks. For internal code, however, I’d recommend going without null checks. Unfortunately, I don’t have enough real-life experience to make a conclusive suggestion yet. What do you think about it? Is that the way to go? Tell us in the comments.

APIs need to be updated: It’s a bit like when the async await pattern was introduced. In order to tap the full potential of the new feature, everyone has to get on board. It’ll take some time for all the frameworks to get updated. Until that, you have to be cautious.
Here’s a simple code snippet that compiles without warnings but throws a NullReferenceException at runtime.

var companies = new[]
{
    new Company { Name = "Microsoft", Founder = "Bill Gates" },
    new Company { Name = "Apple", Founder = "Steve Jobs" }
};

var amazon = companies.FirstOrDefault(_ => _.Founder == "Jeff Bezos");
Console.WriteLine(amazon.Name);

Be More Expressive

Real quick, there’s something else I love about the new feature. You can finally express what’s mandatory and what’s optional. Have a look at the following interface:

interface ICustomer
{
    string Name { get; }
    string? Tag { get; }
}

You immediately see that the name is mandatory, but the tag is optional. That’s fantastic for doing domain modeling! But that’s for another post.

What do you think about the shiny new nullable reference types feature? Is it a step in the right direction? Will we get rid of most NullReferenceExceptions? Or is it a source of confusion, adding to much complexity to the language? Share your thoughts in the comments.

Enterprise Software Development

Azure DevOps

Boards

Repos

Pipelines

Conclusion

Do You Need to Host It Yourself?

Farewell TFVC - It’s Time for Git

How to Set It Up

Yes, It’s Different

Why Git Is Better

A Typical Development Workflow with Git

More Fun with Caching

Higher-Order Functions

Delegates

F#

Cache Class

Cache Method

C# Fun with Caching

Motivation

Direct Approach

The Caller Caches

A Cache Object

SquareCache

Inheritance

Composition

Option Type in C#

The Option Type

There’s More to the Option Type

The Power of Bind

The Missing LINQ

Implementation

Clean Code - Part 2

Names

Methods

Classes

Comments

Successive Refinement

The Boy Scout Rule

Clean Code

The Subtitle Tells You More

What’s to Gain?

Conclusion

A Final Thought

Quality Matters

Which Quality I’m Talking About

Why Quality Is Important for Enterprise Software

What’s Quality?

There’s No Free Lunch

How to Implement List Properties. It’s Not as Simple as It Sounds.

An Iterative Approach

Do You Want to Go the Extra Mile?

Don’t Expose Mutable Objects

Immutability

What Would It Look Like in F#?

C# 8.0 Nullable Reference Types: The End of the NullReferenceException?

Pre C# 8.0: How to Deal with Null

Null Checks

Convention and Discipline

C# 8.0 to The Rescue

… It’s Not a Silver Bullet

Be More Expressive