DEV Community: Richard Keil

The D in SOLID Software Architecture — Dependency Inversion Principle

Richard Keil — Wed, 15 Jul 2020 22:45:22 +0000

„D“ stands for Dependency Inversion and promotes depending on abstractions rather than concrete implementations.

When developing new systems it's usually easy to pay attention to creating modular structures and adhering to the Single Responsibility Principle. As a consequence, one often builds modules that take care of a specific task first and then uses them later in the business logic.

However, this often comes with a downside: These systems are usually tightly coupled because the business logic depends directly on the low-level module.

Dependency Inversion suggests changing („inverting“) this relationship. Instead of directly referencing the low-level module, one ought to reference its abstraction.

Let's have a look at an example similar to the one of the Open-Closed Principle. Actually, this similarity is no surprise because the two principles benefit from each other by removing tight couplings in your code.

class EmailBroadcaster {
  send(event: Event, user: User) {
    const description = `New event ${event.name} occured at ${event.getTimestamp()}`
    emailService.send({ to: user.email, subject: event.name, body: description })
  }
}

class NotificationHandler {
  private mailer: EmailBroadcaster

  constructor() {
    this.mailer = new EmailBroadcaster()
  }

  public broadcast(event: Event, user: User) {
    this.mailer.send(event, user)
  }
}

function onAccountCreated(event: Event, user: User) {
  const notifications = new NotificationHandler();
  notifications.broadcast(event, user)
}

The NotificationHandler instantiates the EmailBroadcaster (hence makes it a direct dependency) and calls it later. This leads to the following problems:

the Handler is not easy to test because one cannot mock the actual EmailBroadcaster — one would need to test both at the same time
the Handler depends on a low-level module which means that it is subject to effects of changes in this low-level module

A potential solution might look like this:

interface Broadcaster {
  send(event: Event, user: User)
}

class EmailBroadcaster implements Broadcaster {
  send(event: Event, user: User) {
    const description = `New event ${event.name} occured at ${event.getTimestamp()}`
    emailService.send({ to: user.email, subject: event.name, body: description })
  }
}

class NotificationHandler {
  constructor(private broadcaster: Broadcaster) {}

  broadcast(event: Event, user: User) {
    this.broadcaster.send(event, user)
  }
}

function onAccountCreated(event: Event, user: User) {
  const notifications = new NotificationHandler(new EmailBroadcaster())
  notifications.broadcast(event, user)
}

In this case, the NotificationHandler requires no knowledge at all about the implementation of the EmailBroadcaster. All it needs to know is that given a „Broadcaster“ it can send notifications.

By putting the Broadcaster interface between the two classes and inverting the relationship, we removed the tight coupling and can now enjoy easy testing and a system that is less prone to ripple-effects of low-level changes.

As you might have noticed, the „new“ keyword did not completely disappear. It merely moved one level up, into the onAccountCreated function. There it would lead to similar problems as in the NotificationHandler in theory.

This is where „Inversion of Control Containers“ (short IoC Containers) come into play. They allow one more level of abstraction by taking care of managing all the dependencies between modules, for example through injecting them automatically into the constructor of a class.

Most modern frameworks come with this ability to „autowire“ out of the box. In our example, it would be likely that the onAccountCreated function is part of a module that can be hooked up through our own or a framework IoC container. Then the NotificationHandler would be instantiated through the container and directly provisioned with a Broadcaster that we could globally configure.

Dependency Inversion is a powerful concept that allows building systems that are more modular and can adapt faster to changing requirements. The principle is the last one of the five SOLID principles.

The I in SOLID Software Architecture — Interface Segregation Principle

Richard Keil — Fri, 12 Jun 2020 15:50:06 +0000

„I“ stands for Interface Segregation Principle and encourages only the implementation of behaviour that is actually required.

In software architecture interfaces are contracts that define no behaviour themself but that other modules must adhere to. They allow the consumer of a module to know how to talk to the module without having to know about details of it.

A metaphor about interfaces

Interfaces are like an image you have in mind of the cashiers at a cinema. You know that you can tell them what movie you want to see and where you want to sit. You know that they are going to ask you for money and that you can give them money. Also, you expect them to hand you your ticket in the end. However, you don't care how they actually get you the ticket (what they type into the computer) or if they go and get the money from a different register. Now if you actually go to the cinema, you can expect that the cashier you meet fulfills all the expectations in your mind, plus some things that each cashier offers on top (for example a little small talk).

The image of the cashier in your mind is the interface. The actual cashier is an implemented class — most probably a subclass of „Human“.

To „segregate“ something means to split it up, separate or isolate it. In connection with the Interface Segregation Principle, the goal is to keep interfaces as specific and oriented towards a single responsibility as possible. If necessary by splitting them up.

Or, as Robert C. Martin states:

„Clients should not be forced to depend upon interfaces that they do not use.“

The problem

Let's check out the following example to see how not honouring this principle might hurt us. The following event broadcasters for email and push notifications both implement a CanBroadcast interface so other services know that they can send notifications with them:

interface CanBroadcast {
  send(event: Event, user: User)
  trackReads(track: boolean)
}

class EmailBroadcaster implements CanBroadcast {
  send(event: Event, user: User) {
    emailService.send({ to: user.email, subject: event.name })
  }
  trackReads(track: boolean) {
    emailService.setConfig({ trackOpens: track ? "always" : "never" })
  }
}

class PushBroadcaster implements CanBroadcast {
  send(event: Event, user: User) {
    const description = `New event ${event.name} occured!`
    pushService.push({ token: user.pushKey, body: description })
  }
  trackReads(track: boolean) {
    throw new Error("PushBroadcaster does not support tracking reads.");
  }
}

As you can see the common CanBroadcast interface makes sure they implement a send and a trackReads method. There is only one catch: The PushBroadcaster has no use for this method, because push notifications do not support read status in our case.

This leads to two issues:

There is an overhead in code. One needs to read the implemented method to understand that it's not relevant for the class.
If one wants to change how notification tracking is handled, one needs to touch code that actually does not care about notification tracking. I described the reason why this is an issue in the Open Closed Principle post.

A solution

We could improve on the two pain points like this:

interface CanBroadcast {
  send(event: Event, user: User)
}

interface CanTrackReads {
  trackReads(track: boolean)
}

class EmailBroadcaster implements CanBroadcast, CanTrackReads {
  send(event: Event, user: User) {
    emailService.send({ to: user.email, subject: event.name })
  }
  trackReads(track: boolean) {
    emailService.setConfig({ trackOpens: track ? "always" : "never" })
  }
}

class PushBroadcaster implements CanBroadcast {
  send(event: Event, user: User) {
    const description = `New event ${event.name} occured!`
    pushService.push({ token: user.pushKey, body: description })
  }
}

Now the email and push notification classes both implement the CanBroadcast interface, however only the email broadcaster implements the CanTrackReads interface.

This way there is no need for throwing exceptions at run time in unnecessary methods. This means classes are easier to read and hence to maintain.

Also changes can be made with higher confidence because one only needs to touch classes that are actually affected by the change.

Last but not least consumers can use the new structure to make sure that they only deal with relevant types — eg. broadcasters that allow for tracking reads.

How to spot violations

Detecting violations of the Interface Segregation Principle is usually easy. One should watch out if

classes implement one-line methods that just return null or throw an exception
the architecture utilizes many layers of inheritance — in this case violations of the principle are often inevitable because one bases subtyping on modifying behaviour instead of only extending it (Barbara Liskov is watching you 👀)

The principle is pretty straight forward and thinking of it while implementing new features will certainly enhance the maintainability of your code. It also plays nicely into the hands of the Solid Responsibility Principle.

The L in SOLID Software Architecture — Liskov Substitution Principle

Richard Keil — Tue, 09 Jun 2020 20:53:37 +0000

„L“ stands for Liskov Substitution Principle and encourages architectures that allow exchanging base classes for their subclasses without breaking things.

Inheritance is a powerful feature in software architecture, especially given the ability to override the behaviour of a base class. If you want to, you can extend a basic class and change its behaviour completely.

This leads to the question of when inheritance should actually be used. Why not use composition instead? How do you know if you should implement a new feature by extending something that already exists and just modify its behaviour or by choosing a completely different pattern?

Barbara Liskov answered this question in a 1987 keynote and later formalized it in another paper in 1994:

Subtype Requirement: Let ϕ(x) be a property provable about objects x of type T. Then ϕ(y) should be true for objects y of type S where S is a subtype of T.

This statement is now known as the „Liskov Substitution Principle” and can be put into words slightly less formal:

When using a base class T, one should be able to exchange this base class T with any subclass S (that inherits from T) and expect the same behaviour ϕ.

Let's consider a simple example in which we want to send a notification email for a given event. We want to be able to either send a normal email or an email for subscribed users which contains additional information about the subscription. For now, we always send a normal email:

As you can see, we have an EmailBroadcaster as well as a SubscriptionEmailBroadcaster who inherits from the former — he does basically the same thing, but a little bit more, so that calls for inheritance, right?

Well, suppose now we want to switch from using our basic EmailBroadcaster to our new SubscriptionEmailBroadcaster. Following the logic from above, we should be able to just exchange the old EmailBroadcaster with the SubscriptionEmailBroadcaster, because it inherits from it. It worked with the parent class, so it should just work™ with the child class as well. After all „it does the same thing, but a little bit more”, right?

If you would try to change it, you would find that it actually does not work because compilation fails. In onAccountCreated we pass either a User or a SubscribedUser (latter could be a subclass of the former) to the broadcast method. However, the new SubscriptionEmailBroadcaster only takes a SubscribedUser.

By modelling our architecture this way, we broke the Liskov Substitution Principle, more specifically the first of the following requirements that should be fulfilled to avoid issues like this:

1. Do no strengthen pre-conditions in subclasses.

The parameter types of sub-class methods should match or be more abstract than the parameter types of base-class methods. In our case, SubscribedUser is a subtype of User — because we require a more specific (instead of abstract) type, we strengthen the pre-conditions.

For example in a simpler case, this rule would be broken by expecting only positive numbers in a subclass method, while the overridden base class method accepts both positive and negative numbers.

The subclass should always be more liberal in what it accepts, not stricter.

2. Do not weaken post-conditions in subclasses.

The return type of subclass methods should match or be a subtype of the return type of base class methods. This also applies to exceptions: Thrown exceptions of subclass methods should match or be a subtype of thrown exception of base class methods. This is to avoid introducing exceptions that would not be caught by code that relies on the base class.

The subclass should always be more strict in what it returns or throws, not more liberal.

So, how could we fix our example? There are basically two ways: Reversing our inheritance structure or using composition.

The first option would mean that the SubscriptionEmailBroadcaster becomes the base class and EmailBroadcaster inherits from it. One could rename the SubscriptionEmailBroadcaster to EmailBroadcaster and the former EmailBroadcaster to AnonymousEmailBroadcaster to reflect that it does not require a subscription:

When starting out with the EmailBroadcaster we could now exchange it for the AnonymousEmailBroadcaster without issues, because it actually reflects inherited behaviour — the subclass can do anything that its base class can do (in terms of its contract).

Following the second option of using composition instead of inheritance could be implemented by using one interface that independent broadcasters adhere to:

In this case, the compiler would also complain if we just exchange AnonymousEmailBroadcaster with SubscriptionEmailBroadcaster (because of the different constructors). However, it is much less of a problem because we have no expectation that the new class should just work-after all, it has no relationship to the other class except implementing the same interface.

The Liskov Substitution Principle is in theory very easy to understand: Just make sure you can exchange your base classes for their subclasses without running into issues.

However, I personally find it much harder to spot in practice. My guess is that this is due to intuitively interpreting the word „inheritance” as „use of common behaviour with modification”.

To make it easier to spot violations I propose to interpret „inheritance” as „use of common behaviour with extension”.

This way we always keep in mind that a subclass builds on top of the behaviour of a base class and does not try to change the initial behaviour.

This article was especially interesting to write because it required some time to come up with a fitting example along the lines of the Event-Notification example of the Single Responsibility and Open Closed Principle post.

The O in SOLID Software Architecture — Open Closed Principle

Richard Keil — Tue, 09 Jun 2020 20:48:09 +0000

Bertrand Meyer first brings up the “Open Closed Principle” in 1988 by writing the famous words

Software entities (classes, modules, functions, etc.) should be open for extension, but closed for modification.

What that means is that there should be little need to modify existing code if we want to implement a new feature. At first, this seems a little contradictory because software changes all the time and so does its code, right? What about refactoring or even fixing bugs?

Let’s look at a concrete example to understand what the principle is trying to promote. The following example is written in Typescript but it’s easy to read– it’s about the underlying thoughts, not the exact code. Suppose we want to react to an event from our application by sending it to a specific channel, in this case, either email, text or push notification.

class NotificationHandler {
  broadcast(event: Event, user: User, broadcastTo: string) {
    const title = event.name
    const description = `New event ${title} occured at ${event.getTimestamp()}`
    if (broadcastTo === "email") {
      return emailService.send({ to: user.email, subject: title, body: description })
    }
    if (broadcastTo === "push") {
      return pushService.push({ token: user.pushKey, content: description })
    }
    if (!user.phone) {
      return;
    }
    if (broadcastTo === "text") {
      return textService.sendText({ to: user.phone, body: description })
    }
  }
}

function onAccountCreated(event: Event, user: User) {
  notifications.broadcast(event, user, "email")
}

This code is hard to extend because every time a new way of sending notifications should be implemented one needs to go into the broadcast() method and add another if-block. This is what one calls „modification“.

When multiple people work on different ways of broadcasting at the same time this will probably result in merge conflicts. Also when a project „grows up“ usually more abstractions are added on top of basic modules.

In our example, that means that other modules could rely on the NotificationHandler broadcasting a given event to the correct channel. So when one makes a little mistake while changing this basic module the mistake will potentially affect all the code that is based on the module. In the example, such a mistake could be to add a new if-block at the end of the method. Whoops. We might have overlooked the if(!user.phone) return that will prevent our new addition to be executed when a phone number is missing. Maybe we did not write a test to cover missing phone numbers for our new feature.

So, how could we stay open for „extending“ our module instead of having to modify it? Consider this:

interface Broadcaster {
  send(event: Event, user: User)
}

class EmailBroadcaster implements Broadcaster {
  send(event: Event, user: User) {
    const description = `New event ${event.name} occured at ${event.getTimestamp()}`
    emailService.send({ to: user.email, subject: event.name, body: description })
  }
}

class PushBroadcaster implements Broadcaster {
  send(event: Event, user: User) {
    const description = `New event ${event.name} occured!`
    pushService.push({ token: user.pushKey, body: description })
  }
}

class TextBroadcaster implements Broadcaster {
  send(event: Event, user: User) {
    if (!user.phone) return
    const description = `New event ${event.name} occured!`
    textService.sendText({ to: user.phone, body: description })
  }
}

class NotificationHandler {
  broadcast(event: Event, user: User, broadcaster: Broadcaster) {
    broadcaster.send(event, user)
  }
}

function onAccountCreated(event: Event, user: User) {
  notifications.broadcast(event, user, new EmailBroadcaster)
}

We implemented the strategy pattern here. Instead of deciding within the NotificationHandler how our event should be brought to the user, we pass the „how“ as a strategy, in this case as a class that implements the Broadcaster interface. The handler can then just send the message through the broadcaster and take care of the common things between all notifications (eg. error handling).

These changes in structure allow us to

add a new way of sending notifications without modifying existing code — we only need to add a new class that implements Broadcaster
develop multiple ways of sending notifications at the same time without conflicts (means higher development speed and hence greater flexibility)
develop new Broadcasters without having to worry about breaking any existing functionality — also we can easily test them in isolation
follow the Single Responsibility Principle by making sure each of our modules has only one reason to change

In general, the Open Closed Principle should be considered when implementing a new feature that is of the same kind as an already existing one. Like in our example a new way of sending notifications.

One can then improve the quality of the code by extracting the different features into their own modules and keeping only the similarities in the base module. Through passing in the feature module, the base module does not need to know what or how many features actually exist — it only relies on their interface.

As Robert C. Martin points out this approach is already heavily adopted by apps that allow for custom plugins:

„I’ve heard it said that the OCP is […] not for real programmers with real work to do. The rise of plugin architectures makes it plain that these views are utter nonsense. […] A strong plugin architecture is likely to be the most important aspect of future software systems.“

When building software according to the Open Closed Principle one should keep its original intention in mind: To simplify adding new features without breaking existing code. There is no use of blindly extracting a one-line statement into its own module.

The Open Closed Principle is often considered to be one of the most important design patterns of software architecture. In my experience, its implementation often shows a direct and positive effect on how quickly new features can be implemented.

Let me know if you found this article helpful or have any feedback — I appreciate all of it!

The S in SOLID Software Architecture — Single Responsibility Principle

Richard Keil — Tue, 09 Jun 2020 19:51:24 +0000

In software development the concept of building complex structures out of basic blocks is omnipresent, be it in the form of classes, components or modules.

According to the SOLID principles, each of these basic blocks should only have one job and defer additional jobs to other modules.

For example, let’s say one wants to react to an event that is thrown within an application. The event should be persisted to the database and a notification email should be sent to users. This could look something like the following (written in Typescript but easy to read - it’s about the principles, not the language):

function onAccountCreated(event: Event) {
  // Persist event in database.
  database.table("events").create({
    name: event.getName(),
    data: event.getPayload(),
    createdAt: time.getISO(event.getTimestamp())
  })
  // Send new account email notification.
  http.post(
    "api.my-email-service.com/send-email",
    {
      to: "me@example.com",
      subject: "New event",
      body: `The event ${event.getName()} has occured!`
    },
    {
      Authorization: config.environment.get("EMAIL_API_KEY")
    }
  )
}

So, what’s the problem with this? There are three:

1. Readability

Code is read much more often than it is written, especially when projects grow larger. Robert C. Martin estimates the ratio at 10:1¹. This means that both from the development and business perspective it makes sense to optimize for reading time.
In the example above the multiple levels of indentation, the length of the method, as well as comments make the code hard to scan.

2. Testability

The presence of tests is usually assumed in every serious software project. Especially when unit testing the ability to mock other services is important to make sure we only test a specific module.
In the example we need to mock four different modules: database, time, http and config. Every mock introduces more complexity — means more room for mistakes and code that is harder to read and understand.

3. Separation of Concerns

Parts of software that have similar responsibilities should be grouped while parts with different responsibilities (concerns) should be separated. Or, as Uncle Bob puts it:

„Gather together the things that change for the same reasons. Separate those things that change for different reasons.“

This is based on the fact that software is ultimately built to serve people. Because of that, it should not only be structured around a specific flowchart of a process but around the people it serves. If a designer requests a change in the layout of the app, one should not need to change code that is concerned about persisting data from this layout to the database. Separation of concerns.

In the example, there are multiple reasons for the code to change, all with different motivations. The backend developer could make a change to the database schema, requiring the DB call to adapt. The design team could make a change to the email styling, requiring the email service request to adapt. The operations team could change the deployment, requiring the configuration to adapt. All of these motivations requiring changing the same piece of code is a recipe for headaches.

So what would be a more suitable solution? Let me suggest this:

function onAccountCreated(event: Event) {
  eventRepository.persist(event)
  notifications.broadcast(event)
}

The repository can take full responsibility on how to persist events:

class EventRepository {
  persist(event: Event) {
    database.table("events").create({
      name: event.getName(),
      data: event.getPayload(),
      createdAt: time.getISO(event.getTimestamp())
    })
  }
}

The notifications module can take care of notifying users by utilizing the mailer:

class Notifications {
  …
  broadcast(event: Event) {
    this.mailer.send(
      "me@example.com",
      "New event",
      `The event ${event.getName()} has occured!`
    );
  }
}

class Mailer {
  …
  send(to: string, subject: string, body: string) {
    this.http.post(
      "api.my-email-service.com/send-email",
      { to, subject, body },
      {
        Authorization: config.environment.get("EMAIL_API_KEY")
      }
    )
  }
}

Even if this creates more lines of code, the overall quality of it is improved:

One can quickly understand what the onAccountCreated method is doing (no comments necessary).
One can investigate only the code that is relevant to one's problem.
Testability is improved by reducing the dependencies of each module.
Code that changes for the same reason is grouped — the EventRepository changes only when the DB schema changes, the Notifications module changes only when the design team wants to make adjustments to the email body and the Mailer only changes when the operations team decides to use a different configuration setup.

By now the benefits and necessity of structuring code this way should be clear.

However, as with most things, one should not just apply the methods promoted by the Single Responsibility Principle blindfolded. Just splitting all your code into own classes until each has only a one-line-method will lead to over-engineered code which is inefficient to work with.

One should understand that the principle is about balancing division with aggregation — based on the reason for certain parts of code to change.

With this understanding, it should be much easier to apply the Single Responsibility Principle in day-to-day development with confidence. Let me know if you found this article helpful or have any feedback — I appreciate all of it!

¹ Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship