Spoiler, it's not. If you think about the system as a product that has to deliver value, thinking about test scenarios ahead of the solution is more manageable.

Imagine the following scenario where we accept a file through an API and want to parse it and read data.
From here, we can take two paths.

1. First one, just do it! Take an expected file, validate it using some method we wrote and then read the data because now we know that file is correct.
2. The second one, think before doing. Ok, we have to read a file. What file can we expect? Is the format fixed? What are we going to do in case of errors? How often will we receive such a file? The list goes on.

The lazy way

Using the first approach, we end up with the following test scenarios:

• When uploading a file, it should store the document
• When uploading a file, it contains duplicates; it should store only distinct documents
• When uploading a file with only not parsable rows; it should not be stored
• When uploading a file and it is not CSV text content type, API should return a bad request

It doesn't sound like a description of business behavior. Furthermore, there are many technical details here, like API and parsable rows. It requires a decent knowledge of the inner workings of the code to understand what's going on.

The product way

Let's take the second path and start by describing expected behavior.

We know that we will receive a file. The file has to be in a specific format, CSV, in our case. It will contain errors, but we can't foresee all kinds of mistakes. When the file is ok, we store it in the database. Who can send us a file?

Now, we can state the problem in the form of test scenarios:

• Receiving a file with errors in the content should create a summary of mistakes. Going further, how do we handle different kinds of problems?
• Discard the empty file.
• The correct file should be stored in a database.
• An unauthorized user sends a file.

I found these scenarios more related to the real problem we are trying to solve. I don't need any knowledge about the details of the implementation. I want to know if we modeled the process correctly.
Additionally, using such scenarios, we can find gaps in our understanding.

It takes time

Taking a more product-oriented approach is a skill that took me years to develop. It helped me in other areas and made me a better software developer.

Remember, part of the system you are working on is a more significant piece of the business process. Focus more on the business, and you will gain a lot.

Throwing an exception is a goto

Exceptions are hidden goto statements. That's one of the most significant troubles with them.
Whenever you notice a method that throws an exception and catches it in another place, stop for a moment. Such early returns make it hard to resonate about program control flow and make code difficult to refactor.

Don't use exceptions for validation

Very often, we use exceptions for validation.
Someone called your method with an empty string? Throw an exception!
Start date is older than the end date? Throw an exception!
Height is a negative number? Throw an exception!

This doesn't mean that exceptions can't be used for validation. For example, they are excellent when verifying input to the web API.

But when working with business logic, take a look at different techniques:

• Type Driven Programming
• Result types widely used in functional programming.

When to throw

Having all that behind us, how do I know that specific situation should be modeled as an exception?
These questions can be helpful to ask:

• Do you know what to do when the case that seems like an exception occurs?
• Is this exception a part of your domain?

If the answer to the first question is positive, just log the issue and move on.
The second question is more subtle and requires a bit of thinking. Scott Wlaschin has an excellent post on this issue

Throw in an elegant way

Finally, if you throw an exception, make the reason obvious.
Name it correctly using language from your domain. Default exceptions are rarely a good idea.
And remember that exceptions are written for other developers. Therefore, there is nothing wrong with keeping it technical.

Live templates

Why not create such a template by yourself?
My problem was that I wanted to pass a stream name to the function but add some prefix to the stream beforehand.
My code looked like this:

eventStore.SaveEvents(streamName, events, eventMaxAge)

After the change, it should look like this:

eventStore.SaveEvents($"rev-{streamName}", events, eventMaxAge)

I've found string interpolation a perfect solution for this issue. But after doing it time and time again, I've got tired of doing it manually. I wanted an easy way to surround stream name with string interpolation.

Using surround template

Then I've recalled that Rider has an option to surround a variable with brackets, for example.
Let's create such a template for string interpolation!
Try this sequence: double press shift, type live template, press enter, and voila!
From this place, you can create a new template. The one I've created looks like this:

How to use it? Mark a variable you want to surround and press the shortcut set up for the "Surround with" command. In my case, it's ctrl+alt+j, but I've found my keyboard shortcuts relatively uncommon.

After applying it using enter or pressing one, it will wrap the variable in a string interpolation like so:

And that's what I need!

Templates are great for automating tedious typing. Who doesn't like IntelliSense tailored to their needs?

let result =
    async {
        let client = new HttpClient()
        let url = "https://api.frankfurter.app/latest?amount=10.99&from=USD&to=PLN"

        let! result =
            client.GetFromJsonAsync<ApiResponse>(url)
            |> Async.AwaitTask

        printfn $"10.99 in USD is {result.Rates.PLN} in PLN"
    }

result |> Async.RunSynchronously

For my taste, it is very similar to the C# code.
The most significant difference lies in the async block. It doesn't run until you do it explicitly!
In the C#, when you create a task, you have no control over when it starts. I've described one of such scenarios here.

Only after calling Async.RunSynchronously the actual workflow runs. It reminds a bit of await instruction in C#, but the inner working is different.

The complete code is available on gist.

I like this functional approach with cold workflows. It seems more intuitive to me. One downside I can see is that it may require more code. But I don't have enough experience with F# to be sure.

Partial application is a concept widely used in functional programming. It's a function that has parameters already baked into it.
Don't worry if this sounds strange. I hope the example will clear up everything.

When using a DI container, it's common to pass a dependency to our class only to pass it down to some other service. It leads to coupling and no clear separation of responsibilities.
What if we could pass a function that has all the dependencies already baked into it? That's precisely how partial application works!

First, create a delegate. It's an abstraction we will pass around.

delegate string ReadById(string id);

Next, we create an implementation.

static class DatabaseReader {
    static string ReadById(Database db, string id) => db.Read(id);
}

Registration is the most tricky part.

builder.Services.AddSingleton<Database>();
builder.Services.AddSingleton<ReadById>(x => 
  id => DatabaseReader.ReadById(x.GetRequiredService<Database>(), id));

Let's stop for a moment and dissect this construct. First, we register a database using the usual approach. Subsequently, we register the ReadById delegate using a partial application. We can use it like so:

class ServiceUsingDelegate {
    readonly ReadById _reader;

   public ServiceUsingDelegate(ReadById reader) => _reader = reader;

   public string DoingWork(string id) => _reader(id);
}

Anytime we call the delegate, under the hood container will inject the database into it. We don't have to care about its dependencies at all! How cool is that?

It allows our service to be solely focused on its task. We don't have to pass any extra params like a logger or mapper into it. We only use the specific function.

I've found such code in one of our projects recently and instantly fell in love with it.

What do you think about it?

It doesn't require a lot of preparation. Just install .Net Core SDK version 5 or higher, and you are ready to go!

You can find my solution on github. But before reading it, I encourage you to try it by yourself. It's enjoyable!

Stay tuned for more posts about applications written using the SAFE stack.

var dbTasks = getDataFromDbTasks();
var otherServiceTasks = GetDataFromServiceTasks();

var dbData = await dbTasks;
var otherServiceData = await otherServiceTasks;

I found this approach very verbose. I prefer to await all the tasks at the same time. That's why we have an extension method in our codebase specifically for this purpose:

public static class TaskAwaiter {
    public static async Task<ValueTuple<T1, T2>> AwaitAll<T1, T2>(
        Task<T1> x,
        Task<T2> y) 
            => (await x, await y);
}

Such AwaitAll method simplifies the above code to this:

var dbTask = getDataFromDbTask();
var otherServiceTask = GetDataFromServiceTask();
var (dbData, otherServiceData) = 
    await TaskAwaiter.AwaitAll(dbTask , otherServiceTask);

That's precisely what I wanted! So far, so good.

But there is one caveat. What if I have a lot of tasks to await? I don't want to add another extension with more and more parameters.

Here Task.WhenAll() method becomes handy. It creates a single task that completes when all the other supplied tasks have been completed.

Usage looks like follows:

var dbTask = getDataFromDbTask();
var singleTaskFromCollectionOfTasks = Task.WhenAll(CollectionOfTasks());

var (dbData, singleTaskData) = 
    await TaskAwaiter.AwaitAll(dbTasks, singleTaskFromCollectionOfTasks);

Armed with these two methods, I can quickly write meaningful and readable code.

GitLab uses Unleash as a feature toggle service. It has a free, open-sourced client for many platforms and can be found on NuGet. However, it is worth noticing that its .Net implementation requires Newtonsoft dependency. So let's try to make use of it in a .Net Core API.

First, we need to configure it. You can find settings in the Operations -> Feature Flags sidebar menu. And then press the configure button. We are interested in the API URL and Instance ID settings from the dialog that pops up. Now it's time to create a new feature flag called feature-is-here setup for all users and all environments to keep it simple.

It's worth examining the documentation because there are valuable strategies around the flags configuration.

Armed with these variables, we are ready to write some code.

public class FeatureFlagsReader {
    readonly DefaultUnleash _defaultUnleash;

    public FeatureFlagsReader() =>
        _defaultUnleash = new DefaultUnleash(new()
        {
              AppName = "whathever-app-it-is",
            InstanceTag = "{Instance ID}",
            UnleashApi = new("{API URL}")
        });

    public bool ReadFor(string flagName) => 
         _defaultUnleash.IsEnabled(flagName);
}

It makes sense to have only one instance of the feature flag client during the whole application lifetime. Therefore I register it as a singleton in default .Net Core DI container.

services.AddSingleton<FeatureFlagsReader>();

Now we can inject it into our controller and use it as we see fit:

    [ApiController]
    public class BeautifulController : ControllerBase {
        readonly FeatureFlagsReader _featureFlagsReader;

        public BeautifulController(FeatureFlagsReader featureFlagsReader) =>
            _featureFlagsReader = featureFlagsReader;

        [HttpGet("/featureFlag")]
        public string GetFeatureFlags() => 
            _featureFlagsReader.ReadFor("feature-is-here").ToString();
    }

The whole code is available on my GitHub.

I think you agree that it's straightforward. Yet, please be aware that Unleash cache the feature flags values, so it takes some time to reflect the changes.

First, we have to run the client. We can do it from the tools menu.

After that, it will pop up with an example request. Let's first get a token from the service that we can use in subsequent calls. You can do it like so:

POST https://reqres.in/api/register
Content-Type: application/json

{
  "email": "eve.holt@reqres.in",
  "password": "pistol"
}

> {% client.global.set("access_token", response.body.token); %}

This call will send a POST request to https://reqres.in/ and save the token in a global variable called access_token.

Now let's get some data:

GET https://reqres.in/api/users/2
Authorization: Bearer {{access_token}}
Accept: application/json

And that's all. We can call our services without getting out of the IDE.
Simple, isn't it?

What's more, you can check a file with requests into your repository to always have them within reach.

I found such an approach wasteful. Why not commit straight to production?

Deployment vs. release

What's the difference between deployment and release?
Deployment happens when a new version of code appears on the server. It doesn't have to be visible yet.
On the other hand, the release means that some new feature is available to some of our users.

There is no need to do both in the same step.

Feature flags

Taking these definitions into account, we should decouple deployment from release. And it's easy to do so with feature flags. They are becoming more and more popular.
Some CI/CD tools (e.g., Gitlab ) have APIs for this job.

Commit to production

Assuming we can hide our code behind a toggle, nothing stops us from pushing straight to production.
So what can we gain from this?

• frequent deployments make our CI/CD pipeline more healthy
• the release is now only a toggle switch
• you can plan releases separately from deployments

Of course, there is also a downside of having to maintain feature toggles. After every release, they become obsolete, and you have to clean them up.
But the amount of time saved on a faster deployment pipeline is more than enough to take care of old toggles.

That's the usual manifestation of primitive obsession. It occurs when you use primitive types like strings or decimals for domain modeling. I argue that the reason behind it is laziness and being scared of introducing too many types.

Type aliases and record types

Luckly, F# got you covered!
Aliases and records make creating new types both enjoyable and easy. Have a look at this code:

type StationName = StationName of string
type StationCode = StationCode of string

type Station =
    { Name: StationName
      StationCode: StationCode }

We just defined Station that consists of a name and a code.
It's plain English! I like how obvious and readable it is. In the end, we don't have to care what's behind these fields. That should be an implementation detail.

If someday we want to change StationCode to a number instead of a string, we do it in one place, and the rest of the code should stay the same.
Yes, it's that helpful!

Custom types requires custom code

There is a caveat, of course.
We can't use the usual string methods on such alias types.
How to deal with this? I will try to address this in another post.

Then the enlightenment came. In one of the projects, I've seen a function used to get the current time.
I've never thought of that! It doesn't need much code to put into use and is simple to test.
Take a look at an example.

First, you create a function for getting the current time and then pass it to the DateRangeCalculator.

public void ConfigureServices(IServiceCollection services)
{
    Func<DateTime> getCurrentTime = () => DateTime.Now;
    services.AddSingleton(_ => new DateRangeCalculator(getCurrentTime));
}

Our calculator implementation can look like this:

public class DateRangeCalculator {
    readonly Func<DateTime> _getCurrentTime;

    public DateRangeCalculator(Func<DateTime> getCurrentTime) =>
       _getCurrentTime = getCurrentTime;

    public DateTime GetLastMonth()
    {
        var currentTime = _getCurrentTime();
        var previousMonth = currentTime.Date.AddMonths(-1);

        return previousMonth;
    }
}

If you prefer a more functional approach, change GetLastMonth method to static and drop the constructor. I will leave it to you as an exercise.

How to test a class with such dependency?
Just replace the implementation in the test like so:

[Fact]
public void PreviousMonthRangeCalculator()
{
    Func<DateTime> currentTime = () => new DateTime(2021, 1,1);

    var result = DateRangeCalculator.GetLastMonth(currentTime);

    result.Month.Should().Be(12);
}

I like this idea because it doesn't require an interface with one method.
When it comes to tests, there is no need to create a mock class.
Less boilerplate, more readable code, what more do you need?

The question arises, how do you spot the important one? That depends on the domain, of course.

As an example, imagine we start modeling a new system for an insurance company. The usual suspects are insurance, policy, the insured person, insured object, and so on. Add user and privileges into the mix and, we are done! We discovered all our database tables.

What's the next step?
We have to add more flavor to our models. The policy will have some end dates, an insured person, and insured objects. The insurance will have insurance amounts and particular cases it covers, e.g., broken leg. Call this risk.
Does it make sense so far? Our model is almost ready!

Finally, we can add behavior. Policy end validation, checking if the policy covers the incident, paying money to the correct person. We are ready to put it somewhere inside our model.

Does it sound familiar? I did many systems like that.

It leads to spaghetti code. It leads to losing information. It leads to generic services. It's throwing up roadblocks for your project. And you did it to yourself.

How to avoid that? Focus on behavior from day one. Try to come up with a way to model business processes. Work on a common language.
Maybe give EventStorming a try? At least try to visualize usages of your system.

After that, try to create a domain model ?

Then I started to use them. Now I can say that this idea makes code more readable and keep classes more coherent.

Before introducing local functions in C# 7, extracting part of the code required a private method. Of course, one can say that it's still hidden from the outside, but it always felt awkward.

Take this code:

class PersonCreator {
  public Person CreatePerson(string login, string email)
  {
    if (!string.IsNullOrWhiteSpace(login) && EmailIsValid(email))
        return new Person(login, email);

    return null;
  }

  private bool EmailIsValid(string email) =>
    Regex.IsMatch(email,
        @"^[^@\s]+@[^@\s]+\.[^@\s]+$");
}

public record Person(string Login, string Email);

This approach isn't flawed. But like EmailIsValid method shouldn't be part of the PersonCreator class, even a private one.

How can we refactor this to a local function?

Our method could look like this:

Person CreatePerson(string login, string email)
{
  if (!string.IsNullOrWhiteSpace(login) && EmailIsValid())
    return new Person(login, email);

  return null;

  bool EmailIsValid() =>
    Regex.IsMatch(email,
        @"^[^@\s]+@[^@\s]+\.[^@\s]+$");
}

We can skip a parameter because of closure.

In the end, it will get compiled to the private method anyway. But I found this code cleaner and easier to maintain.

What's your approach to local functions?

What a pleasant surprise was how less cumbersome it is to do in F#.

The plan is to compare two value objects defined as a type alias:

type StationName = StationName of string

The test doesn't require much code as well.

[<Theory>]
[<MemberData(nameof (stationsData))>]
let ``compare stations correctly`` (station, otherStation, expected) =
    let result = station = otherStation
    Assert.Equal(expected, result)

C# developers, watch out for = comparison!

And now the clou. Take a look at stationsData definition:

let stationsData: seq<array<Object>> =
    seq {
        yield
            [| "Sopot" |> StationName
               "Sopot" |> StationName
               true
               |]
        yield
            [| "Sopot" |> StationName
               "Gdynia" |> StationName
               false |]
    }

Instead of the type definition for stationsData you could omit it and box every value using |> box. I found the former approach more readable.

Anyway, that's all the code you need. Simple, isn't it?

I fall in love with value tuples since their introduction in C# 7. They are perfect when you need a local data structure with a concise syntax. One of the most common usages of this feature is validation. Add to this switch expression, and we have a great combo.

Validating PIN was never so easy:

(bool Success, string ErrorMessage) ValidatePIN(string pin) =>
    pin switch
    {
        null =>
            (false, "Missing value"),
        var p when p.Length > 4 =>
            (false, "PIN is too long"),
        var p when !int.TryParse(p, out _) =>
            (false, "PIN has to be a number"),
        _ =>
            (true, string.Empty)
    };

I'm a big fan of such an approach. I admit it was intimidating at first. But after a few tries of writing code in such a manner, I think this is the way.

A case from the trenches

Let's say we have a collection of some newly created entities. We want to send them to an external service. But it's API isn't convenient. It requires one save call per element.

Sadly, we don't know how numerous our collection is. Therefore it's hard to reckon how many calls we will have to make. I had no idea how to solve this issue.

Bright colleagues to the rescue! They have pointed me to unique code in one of our repositories. Then, they explained it to me until I finally caught it. That part was tricky. It took me a few tries. And the solution goes like that:

async Task ExecuteWithMaxParallelism<T>(
    IEnumerable<T> items,
    Func<T, Task<T>> externalCall
) {
    const int maxParallelism = 10;
    var       queue          = new ConcurrentQueue<T>(items);

    var tasks = Enumerable.Range(0, maxParallelism)
        .Select(
            _ => Task.Run(
                async () => {
                    while (queue.TryDequeue(out var item)) {
                        await externalCall(item);
                    }
                }
            )
        );

    await Task.WhenAll(tasks);
}

The idea behind this piece of code is straightforward. It creates a determined number of tasks and allows them to make external calls in their tempo.

Let's go through it step by step.

First, we create a ConcurrentQueue with all items we have to save. By using the concurrent version of the Queue, we avoid sending the same item more than once.
After that, we spawn a collection of 10 tasks.
Subsequently, those ten tasks will try to pick an item from the Queue and make the request.
Finally, we call Task.WhenAll to synchronize the result.

Using this method, we were able to limit the number of requests. Which, in turn, improved the performance of our service.

• added to the index
• not added to the index
• not tracked at all

It's likely to have the same file added and not added to the index. How is that possible?

Let me introduce partial file staging. What does it do? It allows you to add only specific changes to the index. For example, you want to add only new code without format changes in the whole file.

I'm a big fan of this approach because it allows you to create small semantic commits. There is one catch that always makes me search the docs, though. Git will try to split all the changes for you. You will see each change and decide if you want to stage it or not. But what happens when git is wrong or the change is too big, and it can't split it further?

Of course, you can edit the so-called hunk manually. And this is the place where I always fail.

Let's take a look at an example. After typing git add -p, we see this.

I want to add only one endpoint. This change is too big, so I press e and edit hunk manually.

This picture always looks scary to me. There is some manual under the code, but I never understood it. What to do to keep just one of the changes? Just delete the parts that you don't need!

Now we can save it and close the editor. The current status looks like this:

I have two changes, and only one ready to be committed. I can verify it with git diff --cached

Perfect! And where is the other change? You should see it after git diff.

I'm ready to create two distinct commits.
git commit -m 'Added default endpoint'
And after adding the second change to the index.
git add .; git commit -m 'Ping endpoint'
The final stage looks like this:

Partial file staging is a powerful feature. At first glance, it can look cumbersome and not very intuitive. I use it daily, and after a few tries, it became my second nature.

let extractNumbers (numbers: Input, delimiterType: DelimiterType)
let numbers = extractNumbers (input, delimiterType)

Braces all over the place! How did it happen? Was my initial feeling wrong?

Not at all. I've used it wrong. I didn't know how to declare a function with multiple params. Instead, I've defined a tuple as an input.
An improved version could look like this:

let extractNumbers (numbers: Input) (delimiterType: DelimiterType)
let numbers = extractNumbers input delimiterType

Can you spot the difference?
I've changed the definition of the function. Instead of a tuple, now it takes two parameters. I've only skipped coma between the params. And now I feel much better about this code.

[MemberData(nameof(Data))]
public void EmailValidator_Should_Validate_Correctly(
    string data, bool expected)
{
  var emailValidator = new EmailValidator();
  var result = emailValidator.Validate(data);

  Assert.Equal(expected, result);
}

As you may expect, I wasn't happy with this boilerplate code as well.
But let's focus on something else. I see a few issues with the name of the test:

• it doesn't describe any business behavior
• it's hard to read because it doesn't follow English grammar
• it includes the name of the service

Sadly, this is the desired template of any test you wrote in that specific codebase.

How can we convey any meaning in such a situation? Embrace the MemberData attribute!

Usually, our data collection has a few entries. It can look like this:

public static IEnumerable<object[]> Data =>
    new List<object[]>
    {
        new object[] {
            "donatello@example.com", true,
            "donatello.turtles@example.com", true,
            "leonardo@examplecom", false,
            "leonardo.example.com", false
        }
    };

Do you see the pattern? Try to make use of it and split the entries.
Divide it as follows:

public static IEnumerable<object[]> ValidEmails =>
 new List<object[]>
 {
   new object[] {
    "donatello@example.com", true,
    "donatello.the.turtle@example.com", true,
   }
 };
public static IEnumerable<object[]> InvalidEmails =>
 new List<object[]>
 {
   new object[] {
    "leonardo@examplecom", false,
    "leonardo.example.com", false
 }
};

Follow by the test:

[MemberData(nameof(ValidEmails))]
[MemberData(nameof(InvalidEmails))]
public void Should_Validate_Correctly(string data,bool expected)
{
    var emailValidator = new EmailValidator();
    var result = emailValidator.Validate(data);

    Assert.Equal(expected, result);
}

Of course, one could argue that it won't change much. We can't see that modification in a test runner window. And that's true. We have to open the file and read its content anyway. But it's a step in the right direction.