DEV Community: Renaud Humbert-Labeaumaz

Bringing Meaning to Legacy Code with Parameter Objects

Renaud Humbert-Labeaumaz — Tue, 09 Mar 2021 15:39:19 +0000

Most of the legacy codebases I have work on suffered from primitive obsession. One of the symptoms is the presence of methods with a swarm of int, string or bool parameters. These methods harm the codebase as they are hard to understand and easy to misuse - which could cause bugs and headaches. This article aims to present a simple, yet extremely effective, solution to this issue through the use of parameter objects.

Let’s take the following method signature to illustrate:

string GenerateLoginLink(
    int userId, 
    DateTime? expiryDate, 
    int? maxAllowedClicks, 
    bool notifyOnClick, 
    bool sendLinkByEmail, 
    bool redirectToHomePage, 
    string? redirectUrl
);

This method generates a link that would allow the user to log in to the platform and be redirected to a specific url. This link has an expiry date or a maximal number of clicks allowed. Also, we can optionally send it directly to the user by email and notify an admin when the user has clicked on it.

There are a couple of business rules to be aware of:

expiryDate and maxAllowedClicks are mutually exclusive (i.e. we can only pass one of them as an argument)
redirectUrl is only useful if redirectToHomePage is false

Now, this method presents some issues.

Illegal combinations. In the best-case scenario, providing the method with an expiryDate and a maxAllowedClicks throws an exception or silently gives priority to one of these fields. In the worst-case scenario, it generates an unpredictable behaviour because the case is not handled. Also, what if both are null?
Poor expressivity. The business rules expressed above are far from obvious. Maybe they are documented in the method’s comment but people do not always read the documentation and it can become stale very quickly if we forget to update it (maybe that is the reason why people tend to overlook documentation?). Also, there is absolutely nothing preventing the developer to pass illegal or useless combinations.
Error-prone. Finally, did you notice the 3 consecutive booleans in the method’s signature? How easy would it be to invert two of them by mistake? The method might work exactly as expected and be thoroughly unit tested, you will still have bugs if you don’t use it properly.

The first iteration would be to use a parameter object for this method.

public class LoginLinkConfig 
{
    public DateTime? ExpiryDate {get; set;}
    public int? MaxAllowedClicks {get; set;}
    public bool NotifyOnClick {get; set;}
    public bool SendLinkByEmail {get; set;}
    public bool RedirectToHomePage {get; set;}
    public string? RedirectUrl {get; set;}
}

string GenerateLoginLink(int userId, LoginLinkConfig config);

This change could reduce the risk of error and would make the use of default values easier. However, it would not be very helpful to prevent illegal combinations and increase expressivity.

A solution to tackle these issues is to use the builder pattern. This pattern provides an expressive API to create an object and is particularly useful when it comes to objects with optional fields.

public class LoginLinkConfig 
{
    // Properties are now read-only
    public DateTime? ExpiryDate {get;}
    public int? MaxAllowedClicks {get;}
    public bool NotifyOnClick {get;}
    public bool SendLinkByEmail {get;}
    public bool RedirectToHomePage {get;}
    public string? RedirectUrl {get;}

    // The constructor is private to force the use of the builder
    private LoginLinkConfig(DateTime? expiryDate, int? maxAllowedClicks, bool notifyOnClick, bool sendLinkByEmail, bool redirectToHomePage, string? redirectUrl) 
    {
        ExpiryDate = expiryDate;
        MaxAllowedClicks = maxAllowedClicks;
        NotifyOnClick = notifyOnClick;
        SendLinkByEmail = sendLinkByEmail;
        RedirectUrl = redirectUrl;
    }

    // Notice that the parameter in these methods is not nullable
    public static Builder ExpiringLink(DateTime expiryDate) => new Builder(expiryDate);
    public static Builder LimitedClicksLink(int maxAllowedClicks) => new Builder(maxAllowedClicks);

    public class Builder
    {
        private DateTime? _expiryDate;
        private int? _maxAllowedClicks;
        private bool _notifyOnClick;
        private bool _sendLinkByEmail;
        // We can set sensible default values
        private bool _redirectToHomePage = true;
        private string? _redirectUrl;

        public Builder(DateTime expiryDate)
        {
            _expiryDate = expiryDate;
        }

        public Builder(int maxAllowedClicks)
        {
            _maxAllowedClicks = maxAllowedClicks;
        }

        public Builder WithRedirection(string redirectUrl)
        {
            _redirectToHomePage = false;
            _redirectUrl = redirectUrl;

            // Return the builder to allow chaining
            return this;
        }

        public Builder WithClickNotification()
        {
            _notifyOnClick = true;

            // Return the builder to allow chaining
            return this;
        }

        public Builder SentByEmail()
        {
            _sendLinkByEmail = true;

            // Return the builder to allow chaining
            return this;
        }

        public LoginLinkConfig Build() => new LoginLinkConfig(_expiryDate, _maxAllowedClicks, _notifyOnClick, _sendLinkByEmail, _redirectUrl);
    }

}

With this builder, creating the config object goes from

var maxAllowedClicksConfig = new LoginLinkConfig 
{
    MaxAllowedClicks = 1,
    NotifyOnClick = true,
    RedirectToHomePage = false,
    RedirectUrl = "/myaccount"
};

var expiringLinkConfig = new LoginLinkConfig 
{
    ExpiryDate = DateTime.Now.AddDays(1),
    SendLinkByEmail = true,
    RedirectToHomePage = true
};

var maxAllowedClicksConfig = LoginLinkConfig.LimitedClicksLink(1)
    .WithClickNotification()
    .WithRedirection("/myaccount")
    .Build();

var expiringLinkConfig = LoginLinkConfig.ExpiringLink(DateTime.Now.AddDays(1))
    .SendByEmail()
    .Build();

This new instantiation process is arguably more verbose, but provides the following benefits:

More meaningful. By using a builder, the developer can express what they mean and there is no doubt about it. Since we got rid of the ambiguity, errors are less likely to occur.
No illegal state. As illustrated in the example, there is absolutely no way of representing an illegal state. For instance, if you want to create an expiring link, you cannot also set the _maxAllowedClicks. Otherwise, when you provide a redirectUrl, the _redirectToHomePage is automatically set to false and cannot be changed.
Simpler implementation. Finally, since the business rules described above are embedded into the object creation, there is no need to enforce them into the method - which allows for simpler implementation. Also, other methods can use the config object, knowing that the business rules will always be applied.

Overall, using a parameter object in conjunction with the builder pattern is a very simple way to bring back meaning into your legacy codebase and reduce bugs by making illegal states literally impossible to represent.

Untangling Legacy Code with Events

Renaud Humbert-Labeaumaz — Thu, 04 Mar 2021 17:34:41 +0000

Legacy code is typically characterised by long methods that mix up different concepts and levels of abstraction. In this context, it can be hard to extract behaviour into proper modules because it feels like everything depends on everything and it would require a massive overhaul of the entire codebase. This article proposes to use events to reduce coupling between legacy code and other properly-bounded modules to either extract existing code or add new one.

Let’s say you have a typical UserManager class which features a CreateUser method. Once a user is created, we might want to send a welcome email to set the password and clear a cache somewhere. The initial code looks something like this:

public class UserManager {
    // ...

    public async Task CreateUser(string username) {
        var user = new User { Username = username };
        int userId = await _repository.Add(user);
        await ClearCacheForUser(userId);
        await SendWelcomeEmail(userId, user);
    }

    private async Task ClearCacheForUser(int userId) {
        // ...
    }

    private async Task SendWelcomeEmail(int userId, User user) {
        // ...
    }
}

The first step could be to extract ClearCacheForUser and SendWelcomeEmail to dedicated classes. However, it would not fundamentally change the issue. Indeed, the CreateUser method would still need to know to clear the cache, send the email, and all the other processes that need to happen upon user creation. Thus, the coupling is still there.

A simple solution to remove this coupling is to use events. Before you raise an eyebrow, it’s important to note that using events does not necessarily mean implementing a full-blown event-sourcing architecture with an event store and whatnot (keep in mind that event-driven and event-sourcing are two separate things). As a matter of fact, starting with a very straightforward in-process event bus can go a long way to help untangle your legacy code.

The following code is a complete implementation of an in-process event bus that you can use.

public abstract class MyEvent {}

public interface IEventBus
{
    Task Publish<T>(T @event) where T : EpEvent;

    void Subscribe<T>(IEventHandler<T> handler) where T : MyEvent;
}

public interface IEventHandler<in T> where T : MyEvent
{
    Task Handle(T @event);
}

public class InProcessEventBus : IEventBus
{
    private readonly IDictionary<Type, IList<object>> _subscriptions = new Dictionary<Type, IList<object>>();

    public async Task Publish<T>(T @event) where T : MyEvent
    {
        if (_subscriptions.TryGetValue(typeof(T), out IList<object> handlers))
        {
            foreach (IEventHandler<T> handler in handlers.OfType<IEventHandler<T>>())
            {
                    await handler.Handle(@event);
            }
        }
    }

    public void Subscribe<T>(IEventHandler<T> handler) where T : MyEvent
    {
        if (!_subscriptions.ContainsKey(typeof(T)))
        {
            _subscriptions[typeof(T)] = new List<object>();
        }

        _subscriptions[typeof(T)].Add(handler);
    }
}

Using this minimalist event bus, we can re-write our CreateUser method like this:

public class UserCreatedEvent : MyEvent {
    public int UserId { get; }
    public string Username { get; }

    public UserCreatedEvent(int userId, string username) {
        UserId = userId;
        Username = username;
    }
}

public class UserManager {
    // ...
    private readonly IEventBus _eventBus;

    public async Task CreateUser(string username) {
        var user = new User { Username = username };
        int userId = await _repository.Add(user);

        await _eventBus.Publish(new UserCreatedEvent(userId, username));
    }
}

Now, we can create handlers to process this UserCreatedEvent and do what needs to be done.

public class ClearUserCacheEventHandler : IEventHandler<UserCreatedEvent>
{
    public ClearUserCacheEventHandler(IEventBus eventBus)
    {
        eventBus.Subscribe(this);
    }

    public Task Handle(UserCreatedEvent @event)
    {
        // Clear cache
    }
}

public class SendWelcomeEmailEventHandler : IEventHandler<UserCreatedEvent>
{
    public SendWelcomeEmailEventHandler(IEventBus eventBus)
    {
        eventBus.Subscribe(this);
    }

    public Task Handle(UserCreatedEvent @event)
    {
        // Send welcome email
    }
}

This event bus will not help with scalability as the events are processed synchronously and the Publish method only returns once all the events are processed. However, it can dramatically reduce coupling within the codebase and can act as a stepping stone to make your architecture more event-driven. Moreover, if you need to go further (e.g. two services communicating through events), you already have the abstractions in place to switch the InProcessEventBus for an out-of-process implementation.

In Defence of the Liskov Substitution Principle

Renaud Humbert-Labeaumaz — Fri, 22 Jan 2021 23:17:11 +0000

The Liskov Substitution Principle (LSP for short) is the “L” in the SOLID principles. Even though many people know this principle, at least by name, I cannot keep track of how many times it is skipped when the SOLID principles are being explained. Most of the time, the explanation of the LSP is reduced to stating its name and showing a half-assed example to which nobody can relate!

Perceived Complexity

I think that the LSP is often overlooked because of its perceived complexity, starting with its name. Indeed, this principle is named after the computer science pioneer and Turing Award winner Barbara Liskov, who laid the base for our understanding of modules and abstraction. As such, it is the only SOLID principle that has not a self-explaining name and I believe that it could throw people off.

Funnily enough, Barbara Liskov explained - during a conference talk she gave in 2020 - that someone asked her once what this principle meant and she was pretty confused because she wasn’t even aware of its existence.

It’s Just Semantics

In a nutshell, the LSP means that there must be a semantic relationship between a class and a subclass - sharing methods with the same name is not enough. For instance, stacks and queues may both have add or remove methods but these classes should not inherit from each other as these methods mean completely different things: a stack would work in a last-in-first-out (LIFO) fashion as opposed to first-in-first-out (FIFO) for a queue. Consequently, if your program is built using a queue and you substitute it for a stack, it might not work anymore.

Temper your Expectations

The idea behind the LSP revolves around expectations and contracts. If I use a stack, I expect it to be a LIFO and would not be happy if it turned out to be a FIFO instead. Any subtype of the stack should respect this contract.

We can therefore infer that a subtype violates the LSP if

it expects more than what the contract states (e.g. non-null input, specific concrete type for an interface, etc.)
it does less than what the contract requires (e.g. return null when it shouldn’t, does not return a list in proper order)
it does not implement a method defined in the base class or interface.

The LSP also means that the client code should not rely on something that is not in the contract.

Purposeful Testing or Why the Test Pyramid is a Scam

Renaud Humbert-Labeaumaz — Fri, 15 Jan 2021 17:29:22 +0000

The test pyramid is a metaphor that illustrates the “ideal” weight of tests depending on their granularity. It goes from the unit tests at the base - which are more numerous - to the end-to-end tests at the top - which should be scarce.

It is often opposed to the “ice cream cone” anti-pattern that features a few unit tests and a massive amount of manual end-to-end tests.

I think that this pattern is a good heuristic - especially when your test suite looks like an ice cream cone - but it also yields a lot of sterile discussions, such as

What is a unit test? What is an integration test?
Do I test private methods?
Do I test pass-through methods? Do I test getters, setters?
What is ideal code coverage? Should I go to jail if I have less than 100% coverage?

Purposeful Testing

Behind this click-bait title, I would like to go beyond the test pyramid and start reasoning in terms of purpose rather than form. Whenever I write tests, I make sure to ask myself the following questions, to be sure that my tests are fit-for-purpose:

What is the purpose of this test? Knowing what the test is supposed to check prevents me from trying to test too much and ultimately write something that will hurt me in the long run. Let’s remember that tests are similar to production code in the way that they require maintenance.
What would make this test fail? By trying to answer this question, I often realise that this test’s failure does not mean that it has achieved its purpose. Worse, sometimes the test simply cannot fail. Tests are not supposed to check everything, they should keep passing when something that they are not supposed to cover is broken.
Will it impede our ability to refactor? A test can too heavily be coupled with the production code can actually be counterproductive. Indeed, it would incentivise not to refactor and hurt maintainability. A typical symptom of a test that impedes refactoring is the overuse of mocks.

Test Taxonomy

By applying this reasoning, I identified the following types of test (this list is far from complete and will get updated in the future).

Support Tests

These tests aim to support the development of an algorithm or standalone class (i.e. no dependency). You would typically start with a very straightforward code and incrementally add test cases to increase the scope and add new edge cases. I have found this type of test to be the perfect use case for Test Driven Development.

Plumbing Tests

Plumbing tests ensure that several classes, external libraries, or third-party services work together as intended. In the test pyramid, these tests fall into the generally accepted definition of integration tests. The goal here is not to check all the edge cases but rather the assumptions made about the various APIs.

Use Case Tests

These end-to-end tests make sure that a user scenario works as intended. Use case tests typically include roundtrips to the database and virtually no mocks. They are good candidates for double-loop TDD.

Orchestration Tests

Unless use case tests, orchestration tests rely heavily on mocks. They are relevant for pieces of code that will just enforce a workflow and call other dependencies. For instance, you may want to check that the code triggers a method call when some conditions are met. I usually make sure to keep these tests are extremely lean as too many mocks can seriously impede refactoring.

Developer Experience (DX) Tests

As I always say to everyone willing to listen to me, tests do not only check your code’s behaviour, but also its design and usability. DX tests are extremely valuable when you are creating an API and want to verify that its usage makes sense and is straightforward. These tests should treat the API as a black box and make absolutely no assumptions about its internal behaviour.

Crutch Tests

The crutch tests are particularly useful when you want to tackle messy legacy code and refactor it. The objective is to extract a chunk of code, test it from the outside and rewrite it entirely without touching the tests at all. We can readily notice that these tests will typically include roundtrips to the database. The main challenge of these tests is to find seams to separate the code you want to rewrite from the rest. These seams are a good place to put mocks in place and inject data in the system under test. Once the refactoring is over, some of these tests might become redundant and can be removed.

Confidence Tests

We often read that we should not test third-party libraries because they are already massively tested and it’s not our place to do it. While this may be true, I think it can be useful to test our assumptions about the libraries we use. The confidence tests make sure you understand how an external library works an ensure that it won’t change its behaviour under you (e.g. during an upgrade). By the way, these tests can also apply to your own legacy code!

Documentation Tests

We should always thrive to write the simplest code possible. However, it is sometimes not possible and we have to slip some hacky hacks into the codebase (e.g. optimisations, libraries or language shortcomings, etc.). In this case, I like to write documentation tests that will explain the code’s behaviour so that other developers (or me, in a week) can understand what it does.

Scratch Tests

Scratch tests are short-lived tests that I sometimes use to check an assumption I have about the code. I use these tests to ask the code questions and see what is its answer. I typically delete them as soon as my assumption is verified or discarded.

Takeaways

For years, I struggled with the granularity of my tests because I had the feeling to write some tests for the sake of it. Also, I was refraining myself from writing other tests that would have been useful, because they did not fit in any of the boxes that the test pyramid provides.

When I started to step aside this test pyramid, I realised that I did not care that much about the number of tests or the balance between unit, integration and end-to-end tests. I just write them when I feel that they could bring something to the table.

Also, I noticed that I am using way less mocks than I used to because I don’t force myself to write “pure” unit tests anymore. As a consequence, I feel that tests enable refactoring instead of impeding it.

The Blind Golden Master

Renaud Humbert-Labeaumaz — Fri, 01 May 2020 21:46:38 +0000

As part of my work, I regularly have to refactor/rewrite some part of our system that has little test coverage, if any. Most of the time, the code is too big or complex to write a test suite comprehensive enough to give me the confidence I need in a timely manner. Consequently, I have come to use a characterisation test technique that I called the “Blind Golden Master”.

Characterisation Tests

If you know what a characterisation test is, you can skip this section. If not, bear with me for a moment. A characterisation test aims to check that an already existing piece of code always keeps the same behaviour throughout the changes you make. This behaviour does not need to be correct - if there is a bug in the code, these tests will check that it is still here at the end! Characterisation tests are then extremely useful during refactoring efforts since it is not necessary to understand (or even read) the code to write them.

One of the most usual characterisation test techniques is the Golden Master. The idea is to exercise the code and record its output somehow (e.g. in a file). Then, the test will exercise the code with the same input and check the output against the previously recorded one - the golden master. See here for an example of this technique.

The Blind Golden Master

Sometimes, it is impractical to store the output of the code - or we simply couldn’t be bothered to do it. Sometimes, the new implementation and the legacy one have to co-exist (and evolve) for a while and the only goal is to check that they always both behave the same.

With this technique, the test simply calls both the new and the legacy code and assert that their output is identical. This approach is extremely effective when the method has a limited set of parameters and no side effect.

For instance, I used it to change the template engine for our codebase (C#).

string newResult = _newEngine.Render(templateName, model);
string legacyResult = _legacyEngine.Render(templateName, model);
Minify(newResult).Should().BeEquivalentTo(Minify(legacyResult));

I also used it to change an algorithm that determines the file extension of a document (see the Java codebase here).

FileExtension legacyValue = application.getExtension(country, region);
FileExtension newValue = application.getExtensionV2(country, region);
assertEquals(legacyValue, newValue);

If the algorithm is crucial to the application and there are a lot of potential combinations to test, it is even possible to run the test in production: every time the code is called, it can invoke both the algorithms, compare their output and raise an error if they don’t match, and always return the legacy result. When there is no more error, it is time to switch to the new implementation. This article explains how GitHub rewrote its merge algorithm using this technique.

Conclusion

The Blind Golden Master is an extremely simple technique that provides confidence during refactoring without having to spend hours writing tests for the legacy code. It is a powerful enabler for improvement that does not require any specific tooling or overhead. Since I started using it a few years ago, it has proven a precious addition to my testing toolbox.

ASP.Net Clean Architecture

Renaud Humbert-Labeaumaz — Sun, 21 Oct 2018 21:04:23 +0000

When creating a new project, it is always a challenge to design a clean, coherent and modular architecture. There are guidelines out there to help us achieve this goal but the implementation is not always straightforward. In this blog post, I will propose an implementation of Uncle Bob’s Clean Architecture on an ASP.Net project. The source code of this project can be found on my GitHub.

The main idea of clean architecture is to reduce the coupling between the core business code and the external world (Web, Database, Frameworks). In order to do that, the project can be divided into 3 main modules, that will be described below: Domain, Web and Data.

Domain

This module contains all the core business code. It does not depend on anything else than the .NET SDK and contains sub-modules.

`Entities`

They are the building blocks of the domain and encapsulate the business concepts. Entities are not coupled with any ORM framework. Indeed the domain model can be quite different from the database model!

`Use Cases`

Following Uncle Bob’s definition, they contain application specific business rules and orchestrate the flow of data to and from the entities and implement higher level business rules.

It is important to understand that the domain model should not leak outside of this module. In order to do that, use cases should not take entities are arguments for their methods, but a list of raw arguments. For instance, the use case that submits a new expense looks like the following:

public interface ISubmitExpense
{
    void Execute(Guid userId, string description, long priceWithoutTax, long priceIncludingTax);
}

It is responsible to build an Expense object and apply the relevant business logic.

`Repositories`

In the domain module, repositories are only interfaces that are used by the use cases to access data without any knowledge of the concrete implementations: data can be retrieved from databases, files or external Web APIs, it should not affect the core business logic at all. To reinforce this, repositories take entities as arguments and return entities as well. It is the responsibility of the concrete implementation to handle conversion if needed.

Data

The data module contains the database and ORM configuration and the repositories implementations. Typically, we find the EntityFramework configuration in this module as well as the annotated classes that will be mapped with database entries. Repositories implementation are responsible for converting “database objects” in domain objects:

public void Create(Expense expense)
{
  // Convert the domain object "Expense" into a database object "DbExpense"
  _dbContext.Expenses.Add(DbExpense.FromExpense(expense));
  _dbContext.SaveChanges();
}

This prevents the ORM framework to leak into the domain.

Web

The web module contains all the controllers. It is responsible for handling HTTP requests, converting JSON or XML payloads to objects and invoking use cases:

[HttpPost]
public void SubmitExpense([FromBody] SubmitExpenseCommand expense)
{
  // The controller just invoke the use case with data extracted from the body of the HTTP request
  _submitExpense.Execute(expense.UserId, expense.Description, expense.PriceWithoutTax, expense.PriceIncludingTax);
}

It should not contain any business logic whatsoever. As a consequence, controllers are very lightweight and easy to test.

Dependency injection

In order to achieve low coupling between the modules, interfaces are injected into the constructor of the different classes:

public class SubmitExpense : ISubmitExpense
{

  private readonly IExpenseRepository _repository;

  public SubmitExpense(IExpenseRepository repository)
  {
    _repository = repository;
  }
}

The plumbing is handled by the Startup.cs class where all the implementations of the interfaces are declared:

public void ConfigureServices(IServiceCollection services)
{
  // ...

  // Register "SubmitExpense" as the implementation of "ISubmitExpense"
  services.AddTransient<ISubmitExpense, SubmitExpense>();
  services.AddTransient<IExpenseRepository, ExpenseRepository>();
}

Conclusion

In this architecture, the emphasis is put on the domain. Every other module should adapt to it but it does not depend on anything. This results in lightweight classes that are very easy to understand and test in isolation.

Moreover, the low coupling makes it very easy to change the infrastructure. Indeed, the domain module would not change a bit if we decided to have a CLI instead of a Web App or if the data should be retrieved from an external Web API instead of a PostgreSQL database.

C# for the Java Developer: Enums

Renaud Humbert-Labeaumaz — Sat, 20 Oct 2018 17:54:27 +0000

Enums is a very common concept. It exists, of course, in Java and C# as well. However, Java and C# enums do not have the same capabilities. This blog post aims to show their differences.

In Java, enums are very much like regular classes: they can implement interfaces and have methods. However, they cannot inherit other classes or be explicitly instantiated. They can be viewed as final classes (or sealed classes in C#) that already inherit the virtual “enum” class, only have private constructor(s) and a set of pre-defined instances (the values of the enum).

For instance, let’s take the example of the HTTP status codes. In Java, it is possible to write this code:

enum HttpStatus implements Comparable<HttpStatus> {
  OK(200), SERVER_ERROR(500), NOT_FOUND(404);

  private final int code;

  HttpStatus(int code) {
      this.code = code;
  }

  // This is a regular instance method
  int code() {
      return code;
  }

  // This is the implementation of the Comparable interface
  @Override
  int compareTo(HttpStatus o) {
      // Http statuses will be sorted by status code
      return Integer.compare(code, o.code);
  }
}

HttpStatus status = HttpStatus.OK;

// The 'code' method can be invoked like any other method
int code = status.code();

In C#, enums are just integers in disguise. The previous snippet can be simulated in C# only because the code attribute happens to be an int. Otherwise, it would be very complex to have the same behaviour:

enum HttpStatus {
  // int value of the enum can be forced to a specific value
  OK = 200,
  NOT_FOUND = 404,
  SERVER_ERROR = 500
}

HttpStatus status = HttpStatus.OK;

// The enum can be casted to an int to get its value
int code = (int) status;

To sum up, Java enums are much more powerful than their C# counterparts. I often use these features when I write Java code and I think I would miss them if I had to write C# code on a daily basis.

C# for the Java Developer: Lambdas

Renaud Humbert-Labeaumaz — Sat, 20 Oct 2018 11:37:12 +0000

A lambda is an anonymous function that can be assigned to a variable, passed as an argument of a method and invoked at any time. We can find lambdas in Java and C# and the resulting code is very similar. A Java lambda can be viewed as the implementation of an interface with only one method (called a functional interface) whereas a C# lambda can be assigned to a delegate, which is a concept that does not exist in Java. This article aims to explain how lambdas work in Java and C# and highlight their differences and similarities.

Java Functional Interfaces

In Java, a lambda can simply be viewed as an anonymous function that implements an interface with only one method. This kind of interface is called a functional interface and can be annotated with the @FunctionalInterface annotation that tells the compiler to enforce the only-one-method rule:

@FunctionalInterface
interface Printer {
  void print(String message);
}

// The function interface is implemented with a lambda
Printer standardPrinter = message -> System.out.println(message);

// The print method of standardPrinter can be invoked
standardPrinter.print("Hello World!");

From the previous snippet, you should note that the way the interface is implemented makes absolutely no difference. It can be a lambda, a concrete class or even an anonymous class. Anyways, you can simply invoke the print method of the interface.

There are some pre-defined generic functional interfaces in the JDK that can be used directly off the shelf. The main ones are described below:

Name	Method	Role
`Function<T,R>`	`R apply(T t)`	Takes an argument of a given type T and returns an object of type R
`Consumer<T>`	`void accept(T)`	Takes an argument of a given type T and does something useful (typically with side effects)
`Predicate<T>`	`boolean test(T)`	Takes an argument of a given type T and returns a boolean (similar to `Function<T, Boolean>`)
`Supplier<T>`	`T get()`	Returns an object of type T

C# Delegates

In C#, a lambda can be assigned to a delegate which is a type that encapsulates a method:

delegate void Print(string message);

// A lambda is assigned to the delegate
Print print = message => System.Console.WriteLine(message);

// print can be directly invoked as a method
print("Hello World!");

Like in Java, some delegates are already defined in the .NET framework, the main ones are described below:

Method	Role
`TResult Func<in T,out TResult>(T arg)`	Takes an argument of a given type T and returns an object of type TResult
`void Action<in T>(T obj)`	Takes an argument of a given type T and does something useful (typically with side effects)
`bool Predicate<in T>(T obj)`	Takes an argument of a given type T and returns a boolean (similar to `Func<T, bool>`)

Conclusion

From a Java perspective, using lambdas in APIs (like Linq for instance) is pretty straightforward. However, when digging a little bit deeper, there are some subtle differences to understand. I find the Java approach simpler as it does not introduce another concept but the C# approach is cleaner because the delegate can be invoked directly like a method.

C# for the Java Developer: Generics

Renaud Humbert-Labeaumaz — Fri, 19 Oct 2018 16:57:36 +0000

In my journey into the C# world, I wanted to talk about generics. Generics exist in both Java and C# languages but their implementation is very different. This blog post aims to explain the differences and similarities between the two.

TL;DR Java generics are a lie, C# generics are not.

Java Generics are a Lie

Generics have been introduced in Java 5. Before that, you had to manipulate Objects and cast them to the desired type:

List apples = new ArrayList();
apples.add(new Apple());
// This is really a list of objects, so the cast is required
Apple firstApple = (Apple) apples.get(0);

In the previous snippet, you should note that there is absolutely nothing that prevents you from adding a Banana into the list and make the program crash at runtime. Also, this code is still valid in the latest version of Java (which is Java 11 as we speak). To say the least, this approach is not very safe and do not leverage the type system as much as we could expect.

Since Java 5, it is then possible to use the generic version of the List class:

List<Apple> apples = new ArrayList<Apple>();
apples.add(new Apple());
// The cast is not required any more thanks to the generics
Apple firstApple = apples.get(0);

The thing is that, at runtime, the two previous snippets are strictly equivalent. Indeed, Java generics are removed during compilation and the resulting bytecode only manipulate Objects and casts. This is called type erasure. As a consequence, it is not possible, in Java, to write code like this:

/**
 * Filter objects of the given type
 */
<T> List<T> filterObjectsOfType(List<Object> objects) {
  List<T> filteredObjects = new ArrayList<>();
  for (Object o : objects) {
      if (o instanceof T) {
          filteredObjects.add((T) o);
      }
  }
  return filteredObjects;
}

Indeed, the type of T is erased at runtime and the instanceof operation cannot be performed. That is why a class object is often passed as an argument of the method:

/**
 * Filter objects of the given type
 */
<T> List<T> filterObjectsOfType(List<Object> objects, Class<T> clazz) {
  List<T> filteredObjects = new ArrayList<>();
  for (Object o : objects) {
      if (clazz.isInstance(o)) {
          filteredObjects.add((T) o);
      }
  }
  return filteredObjects;
}

This method can be invoked like this:

List<String> stringsOnly = filterObjectsOfType(Arrays.asList("hello", 2), String.class);
// stringsOnly contains only "hello"

C# Generics is a Runtime Feature

C# generics, on the other hand, is a totally different beast. Indeed, the real type is kept at runtime and it is possible to use this type to write this kind of code:

/**
 * Filter objects of the given type
 */
public IEnumerable<T> FilterObjectsOfType<T>(IEnumerable<object> objects)
{
    List<T> filteredObjects = new List<T>();
    foreach (var obj in objects)
    {
        if (obj is T)
        {
            filteredObjects.Add((T) obj);
        }
    }
    return filteredObjects;
}

This method can be invoked like this:

IEnumerable<String> stringsOnly = FilterObjectsOfType<String>(new List<object>(new object[] { "hello", 2 }));
// stringsOnly contains only "hello"

Conclusion

In Java, generics are used to write type-safe code but this feature is limited and the code can be awkward sometimes due to the type erasure mechanism. In C#, it is a runtime feature and its usage is much more straightforward.

PS: I realize that the code I wrote in the snippets is not really idiomatic but I wanted to have Java and C# code as similar as possible to be able to focus only on the usage of generics.

C# for the Java Developer: Extension Methods

Renaud Humbert-Labeaumaz — Fri, 19 Oct 2018 12:20:24 +0000

After spending several years crafting Java code, I recently decided to dive back into C# and share what I learn in the process. In this blog post, I will talk about extensions methods. This concept, which exists in some JVM languages (like Kotlin) but not in Java, let the developer add methods to a class without touching its code (hence the name extension methods).

Let’s say you want to create a method that puts the first letter of a string in upper case and returns the new string. You cannot modify (or even inherit) the String class in Java to add this method. Since you don’t necessarily want to create your own custom flavour of the String class for your code base, you would probably create a static function that takes a String as an argument and return another String:

class StringExtensions {
  static String capitalize(String word) {
      return Character.toUpperCase(word.charAt(0)) + word.substring(1);
  }
}

Now, you can simply invoke this function like this:

String word = "hello";
String capitalizedWord = StringExtensions.capitalize(word);

Of course, creating a static method is also possible in C#. However, C# has a feature that allows adding new methods to a class without having to modify its code. This feature is called extension methods. In order to create an extension method, you have to create a top-level static class and implement a static method. The first argument of this method specifies the type that the method operates on and should have the this modifier:

static class StringExtensions
{
  static string Capitalize(this String word)
  {
      // Note that this cannot access any private data in the String class. 
      return char.ToUpper(word[0]) + word.Substring(1);
  }
}

In order to use it, the namespace that contains the class must be specified with a using directive. Afterwards, the method can be invoked as if it was an instance method of the type:

string word = "hello";
string capitalizedWord = word.Capitalize();

Extension methods are very powerful. Besides the fact that the code looks “cleaner”, it is also possible to seamlessly plug new behaviours in existing types by simply importing a namespace. The extension code can be in separate specific modules that can be imported only when needed.

What is a Volatile Variable in Java?

Renaud Humbert-Labeaumaz — Fri, 21 Sep 2018 10:13:33 +0000

The volatile keyword is one of the less known and less understood keywords of the Java language. The goal of this article is to explain what it is and when to use it.

Memory Architecture

In order to understand the value of volatile, one must first understand the memory architecture of a computer:

Each CPU contains its own registers, which are basically in-CPU memory. Accessing these registers and performing operations on variables here is very fast. Each CPU also has cache memory layers. It can access this cache memory fast, but not as fast as the registers. Finally, there is the main memory (also called RAM). All CPUs can access this memory. The main memory is much bigger than the cache memories of the CPU.

Typically, when a CPU needs to read something from the memory, it will read it into its CPU cache memory and perform operations on it. It can even read it into its registers. When the CPU needs to write it back to the memory, it will flush its registers to the cache memory and eventually, this cache memory will be flushed back to the main memory.

In general, the flush is performed when the CPU needs to make room for other information. Thus, it seems clear that one cannot make any assumption about when this flush will occur.

Visibility of Shared Variables

If a computer has 2 CPUs or more, it will be able to run several threads at the same time. It means that, if each thread wants to access the same variable, each CPU will have a “copy” of this variable into its cache memory and this could lead to a major synchronization issue.

Take this code for instance:

public class MyServer implements Runnable {
    private boolean running = true;

    @Override
    public void run() {
        while (running) {
            // Do some very interesting stuff...
        }
    }

    public void stop() {
        running = false;
    }
}

It is very likely that the stop method will be called from a different thread than the one executing the run method. If these threads are executed on 2 different CPUs, the run method will not stop until the CPU has flushed its cache memory to the main memory. And we saw that there is no way to predict when this will happen.

In Java, the volatile keyword explicitly ask for a variable to be directly written to the main memory, and thus becoming instantly available for all CPUs.

The code then becomes:

public class MyServer implements Runnable {
    private volatile boolean running = true;

    @Override
    public void run() {
        while (running) {
            // Do some very interesting stuff...
        }
    }

    public void stop() {
        running = false;
    }
}

Note that a volatile variable can be a primitive or an object and can be null.

When to Use `volatile`

A volatile variable is guaranteed to have its last version always available from every CPUs. It is typically used for flags that are modified by a thread and read by another one (like the running boolean in the previous snippet). Globally, you may use a volatile variable if the variable may be accessed by several threads and you don’t need to perform a sequence of operations in an atomic manner (you should not increment a volatile variable for instance). If you need to do so, you should consider using a synchronization mechanism.

Conclusion

The volatile keyword is seldom used, maybe because messing with threads is frowned upon in a JEE (or Spring) application, but it can be very useful to know it and understand its usage. Indeed, it could make your code safer and prevent you from writing algorithms that rely on locks and synchronization where it’s not really needed.

Intersection Types in Java

Renaud Humbert-Labeaumaz — Wed, 19 Sep 2018 09:29:15 +0000

This blog post aims to explain how we can use intersection types in Java when we expect an object that implements different interfaces.

Interface Segregation Principle

The Interface Segregation Principle (ISP) stipulates that interfaces should contain the least amount of methods as possible. In other terms, a client of an interface should use all the methods of this interface.

For instance, let’s take this File interface:

interface File {
  Collection<String> readLines();
  void write(String line);
  void deleteFile();
}

class LocalFile implements File {
  // ...
}

As a client of this interface, it is highly unlikely that I need all methods. I may want to just read the file and, in that case, I certainly don’t want to be able to delete it. If I just want to delete the file, I probably don’t want to read all its lines.

In order to avoid that, it is a good idea to split this interface into 3 separate ones:

interface FileReader {
  Collection<String> readLines();
}

interface FileWriter {
  void write(String line);
}

interface FileDestroyer {
  void deleteFile();
}

class LocalFile implements FileReader, FileWriter, FileDestroyer {
  // The concrete class can implement all 3 interfaces
  // ...
}

Now, a client can just require the interface it needs and ignore the rest.

Interface Combination

Writing tiny interfaces is good to enforce ISP and lower the coupling of the code. However, what happens when a client wants to read a file and write at the same time?

The first two snippets won’t compile because one of the interfaces is not implemented:

void readAndWrite(FileReader reader) {
  reader.readLines();
  reader.write("Hello"); // That won't compile since reader does not implement FileWriter
}

void readAndWrite(FileWriter writer) {
  reader.readLines(); // That won't compile since writer does not implement FileReader
  reader.write("Hello");
}

As an alternative, it is possible to pass an instance of LocalFile but it introduces a high coupling between the method and the LocalFile concrete class, defeating the whole purpose of interfaces entirely.

void readAndWrite(LocalFile file) {
  file.readLines();
  file.write("Hello");
  // That will compile but it is not recommended
}

Since Java 1.5, and the introduction of generics, a feature, known as Intersection Types, allows to combine interfaces in this kind of situation.

Intersection Types to the Rescue

The following code uses intersection types to solve the issue of needing an object that implements several interfaces:

<T extends FileReader & FileWriter> void readAndWrite(T file) {
  file.readLines();
  file.write("Hello");   
}

The & symbol means that the method expects a type T that implements both the FileReader and FileWriter interfaces.

Conclusion

The intersection types is a feature that is not widely used in Java. However, it is very powerful as it allows to write very tiny interfaces and combine them on demand. From now on, there is no excuse to write big fat interfaces that have dozens of totally unrelated methods!

DEV Community: Renaud Humbert-Labeaumaz

Bringing Meaning to Legacy Code with Parameter Objects

Untangling Legacy Code with Events

In Defence of the Liskov Substitution Principle

Perceived Complexity

It’s Just Semantics

Temper your Expectations

Purposeful Testing or Why the Test Pyramid is a Scam

Purposeful Testing

Test Taxonomy

Support Tests

Plumbing Tests

Use Case Tests

Orchestration Tests

Developer Experience (DX) Tests

Crutch Tests

Confidence Tests

Documentation Tests

Scratch Tests

Takeaways

The Blind Golden Master

Characterisation Tests

The Blind Golden Master

Conclusion

ASP.Net Clean Architecture

Domain

Entities

Use Cases

Repositories

Data

Web

Dependency injection

Conclusion

C# for the Java Developer: Enums

C# for the Java Developer: Lambdas

Java Functional Interfaces

C# Delegates

Conclusion

C# for the Java Developer: Generics

Java Generics are a Lie

C# Generics is a Runtime Feature

Conclusion

C# for the Java Developer: Extension Methods

What is a Volatile Variable in Java?

Memory Architecture

Visibility of Shared Variables

When to Use volatile

Conclusion

Intersection Types in Java

Interface Segregation Principle

Interface Combination

Intersection Types to the Rescue

Conclusion

`Entities`

`Use Cases`

`Repositories`

When to Use `volatile`