Free eBook - Software Architecture with Spring 5.0

This scenario occurs when we create software architectures using frameworks and programming languages that we already know about, without paying close attention to business needs.

Let's say that the ABC company needs an application for manipulating text from large log files. If someone were to ask to work on this requirement, then they will choose a programming language that they are comfortable with during the development process, instead of looking for the best approach elsewhere.

Imagine that the person in charge of creating this application has already mastered JavaScript. In this case, do you think it's a good idea to write code using Node JS or another JavaScript framework running on the server in order to write an application to manipulate log files? I'm not saying that this is impossible—you can do it. However, do you think an application created using this approach will be able to perform and scale better than a system written in Perl, Python, or C, for example? This is not to say that JavaScript is terrible—it is simply important to know that this approach is not a good fit for JavaScript.

We all want to stay ahead with technology, using the latest trends in the programming world to have a better technological background and consequently land cool jobs. Some people tend to write applications, keeping this idea in mind. Let's explain this scenario using the application example for manipulating log files that we mentioned in the previous section.

Suppose you're asked to solve the problem that we mentioned in the I know my land section. In this scenario, your only concern is technology. For instance, let's say you want to try the newest features in the latest PHP release. In this case, you will build this application using PHP. While this programming language has been improving over the last few years since Facebook started to add new features to it, the idea behind writing an application to manipulate large log files using PHP is crazy. As you may know, this programming language is intended to create other kinds of applications—mainly those that have to be accessed using a web browser and without high transactional requirements.

Again, you can write an application using PHP to manipulate large log files, but what will happen when more features are needed? Do you think a software architecture created with this approach in mind will be able to respond quickly to new requirements and the inherent characteristics of the application used in this example?

While we can't predict each detail of an application when we are creating it, we can keep some apparent assumptions in mind to avoid glaring mistakes, like the ones exposed in the preceding sections. Even if you have created an application using the wrong approach, one part of the software architecture process is to evaluate the code base from time to time and take corrective actions based on this. This is important because the existing software architecture needs to evolve in order to avoid becoming useless. During the development process—and because we do not want to miss the established project deadlines—weoften use the FIXMEandTODOtags. However, we should pay close attention to these and take action as soon as we can, as they represent a technical debt that gets worse as time passes. Imagine how easy it is to get rid of a recently introduced debt in the next iteration. Now, imagine how hard it would be if the developer who added that debt is no longer working on the project or even within the same company.

The process of improving the existing software architecture sometimes tends to be even more interesting than creating a new one from scratch. This is because you now have more information about the business requirements and how the application was performing at the time that it was in production.

When you are adding new features to an existing application, you will figure out how good the initial idea was. If the process of adding new features is simple and requires only a few changes in its structure, then we can conclude that the software architecture is doing its job well. Otherwise, if we need to make substantial changes to the underlying parts of the original design, we can say that the initial idea and assumptions were all wrong. However, at this point, the team in charge of the product should be responsible enough to make it evolve instead of writing additional patches to support new features.

Even though patching something sounds similar to making it evolve, it isn't. This idea is explained clearly in the book Building Evolutionary Architectures, written by Neal Ford, Rebecca Parsons, and Patrick Kua.

Proactive teams continually apply changes that make it possible to better support preexisting and new features rather than simply sitting and waiting for chaos when things get out of control. There's nothing wrong with changing an initial design, and it's always worth doing this. The following diagram illustrates this process, as applied to a geometric shape:

Evolving original designs

Now that we know that business needs must guide the application architecture, we can conclude that if it is unable to support new features, then new business opportunities will be missed, making the application and its architecture useless.

A component is a set of functions, data structures, and algorithms that solve one problem. This means that all the code and artifacts that are used to build the component have a high cohesion with each other; the rule here is that the classes or files that create a component should change at the same time and for the same reason.

Software architecture is built using many components, and you should not be worried about having an excessive quantity of these. The more components you write, the more freedom there is to assign them to different developers or even to different teams. Large software architectures can be created using many smaller components that can be developed and deployed independently of each other.

Once we connect these components to each other, they allow us to create the desired software architecture.

As shown in the following diagram, we can see the components as pieces of a puzzle that come together to form an application:

Components forming a larger application

The connected components define application architectures, and their designs describe how each component has been created internally. It's here that pattern designs and SOLID principles must be used to create good designs.

Low coupling refers to the degree to which components depend on each other by their lower structures instead of their interfaces, creating a tight coupling among them. Let's make this easier to understand by using a simple example. Imagine that you need to work on the next user's story:

As a bank customer, I want to receive my bank statement by email or fax in order to avoid having to open the bank application.

As you may discover, the developer should work on two things to solve this problem:

The first requirement seems quite straightforward. To test this implementation, we would use something fairly simple, such as the following code:

@Test 
public void 
theNotificationChannelsAreSavedByTheDataRepository() 
throws Exception 
{ 
  // Test here 
} 

For the second requirement, we will need to read these preferred notification channels and send the bank statement using them. The test that will guide this implementation will look like the following:

@Test 
public void 
theBankStatementIsSendUsingThePreferredNotificationChannels() 
 throws Exception 
{ 
  // Test here 
} 

It is now time to show a tightly coupled code in order to understand this problem. Let's take a look at the following implementation:

public void sendBankStatement(Customer customer) 
{
  List<NotificationChannel> preferredChannels = customerRepository
.getPreferredNotificationChannels(customer);
BankStatement bankStatement = bankStatementRepository
  .getCustomerBankStatement(customer);
preferredChannels.forEach
  (
    channel -> 
    {
if ("email".equals(channel.getChannelName())) 
      {
notificationService.sendByEmail(bankStatement);
} 
      else if ("fax".equals(channel.getChannelName())) 
      {
notificationService.sendByFax(bankStatement);
}
    }
  );
}

Note how this code is tightly coupled with the implementation of the NotificationService class; it even knows the name of the methods that this service has. Now, imagine that we need to add a new notification channel. To make this code work, we will need to add another if statement and invoke the correspondent method from this class. Even when the example is referring to tightly coupled classes, this design problem often occurs between modules.

We will now refactor this code and show its low-coupled version:

public void sendBankStatement(Customer customer) 
{
  List<NotificationType> preferredChannels = customerRepository
.getPreferredNotificationChannels(customer);
BankStatement bankStatement = bankStatementRepository
.getCustomerBankStatement(customer);
preferredChannels.forEach
  (
    channel ->
notificationChannelFactory
    .getNotificationChannel(channel)
    .send(bankStatement)
  );
}

This time, the responsibility to get a notification channel is passed to the Factory class, no matter what kind of channel is needed. The unique detail that we need to know from the channel class is that it has a send method.

The following diagram shows how the class that sends notifications was refactored to send notifications using different channels and support an interface in front of the implementations per notification channel:

Classes after refactoring

This small but significant change has to lead us to encapsulate the details of the mechanism used to send notifications. This exposes only one well-defined interface that should be used by the other classes.

Although we have shown this example using classes, the same principle is applicable to components, and the same strategies should be used to implement them and avoid coupling among them.

The principle of high cohesion also has a pretty simple definition: one component should perform one and only one well-defined job. Although the description is pretty simple, we often tend to get confused and violate this principle.

In the previous example, we had NotificationService, which was in charge of sending notifications by email and fax. The word and can be helpful for us when it comes to identifying the violation of this principle. Now that we have two different classes (one per notification channel), it's fair to say that our classes only have one responsibility.

Again, the same is true for components, and another reason to keep the same idea with them is that you will likely have each component accomplishing only one specific requirement. For example, what would happen if all our customers just wanted to receive their bank statements by email; do you think it's okay to depend on a class that has the ability to send faxes too?

Although the previous question may seem unimportant, imagine that you solved an existing issue related to sending notifications using faxes as a notification mechanism, and a new issue was then introduced into the mechanism in order to send email notifications by mistake.

Remember that components shape your software architecture, and architects should design them in a way that maximizes team productivity. Aligning your components to the high-cohesion principle is an excellent way to separate them and allows teams to work independently on different parts of your application. This ability to create various components with clear responsibilities will make it easier when solving other issues and adding new features, and will also make you less prone to introducing bugs.

With regards to the previous example, you are probably wondering why the NotificationChannel class is apparently sending notifications with a BankStatement parameter.

Common sense leads us to believe that we need to replace this class with any other generic type. It can be helpful to allow the application to send different kinds of notifications, and not only bank statements: this may include drawbacks, or when a new deposit is received in the account. Even though the idea of supporting incoming requirements looks like something you might want to include in the program at this stage, the application doesn't currently need this ability. This is why it is not necessary for us to add this feature right now. Instead, this design should evolve when this becomes necessary; in this way, we are sticking to the KISS principle (https://www.techopedia.com/definition/20262/keep-it-simple-stupid-principle-kiss-principle) and following the directions of only building the most basic features to make the application work.

The SRP is very closely related to the high cohesion that we reviewed earlier. The idea behind this principle is that a module should be changed for one reason only. 

This definition leads us to conclude that a module should have only one responsibility. One way to verify whether this principle is achieved in your design is to answer the following questions:

The answer should be yes. For example, if the module's name refers to the domain, then the module should contain domain classes and some functionality around the domain objects related to the module's name itself. You won't want to have code to support audit elements or any other aspect out of the scope of the module you are working with, for example. If the module is supporting additional features, the code supporting those additional features should probably need to be moved to an existing audit module, or a new audit module should be created.

The answer to this question should be many of them; all classes in the module are highly connected, and a new change will change them for this reason. The desired behavior is prevented from being changed through the exposed interface, but the background implementation is often volatile.

The OCP is simple to write, but difficult to explain. For this reason, I'll write the following definition first and describe it later:

New features can be added to an existing module by extension and not by modification.

It sounds simple, doesn't it? In order to understand this concept from a practical viewpoint, it is necessary to revisit our last example. Let's check that we are accomplishing this principle by answering the following questions:

We need to write a new class (module), and this should implement an existing interface. Note how the open-closed principle makes sense with the provided answer. To support a new notification channel in our application, we need to create a new class, but we don't need to modify the existing code. According to the previous refactoring that we made, if we needed to support this requirement, we had to adjust the existing service to send notifications.

A few questions to validate how well this principle is achieved are as follows:

No. If you're looking to add a new feature, you will write a new class instead of modifying an existing one. This is because you are adding and not changing features.

Hopefully, just a little bit. In a perfect world, you won't need to modify anything, but sometimes a few sections should be changed to support new features in the real world. The rule here is that if you are adding a new feature, your original design should be able to support this requirement with minimal changes. If this is not true, refactoring or changing your initial design is recommended.

Big source code files are a bad idea, and there is no reason for them to be large. If your source code file has hundreds and hundreds of lines, revisit your functions and think about moving code to a new file in order to make the source code files smaller and easy to understand.

This is a tricky one. If you only have one concrete implementation for something, you won't need to have an abstract class or interface. Writing code and inventing new possible scenarios is not desirable at all, but if you have at least two concrete implementations that are related to each other, you have to think about writing an abstraction for them. For example, if we only need to send email notifications, there would be no reason to write an interface for this. However, since we are sending notifications via two different channels, we certainly need an abstraction to deal with them.

The Liskov substitution principle (LSP) has a fancy definition:

Module A can be replaced by module B as long as B is a subtype of A.

Well-defined contracts heavily support this definition and help us reduce the coupling between modules. The following questions can help you figure out how well this principle is achieved:

Here, the answer should be that the modules should not be interacting with either option. There is no reason to establish interactions among modules by using their concrete implementations instead of their interfaces.

I hope not. If so, it's because the interface is not well-designed, and a new one should be created to avoid this behavior. The use of the instanceOffunction is also not desirable at all.

There is no reason for this to be the case. Your modules should be connected in a way that can be taken care of by the use of an interface and the correct dependency injection to solve their concrete implementations.

The principal motivation of the interface segregation principle is aligned with the lean movement where creating values with fewer resources is essential. Here's a short definition for it:

Avoid things that you don't use.

You may have already seen classes (modules) implementing interfaces with some method implementations, such as the following:

public  class Abc implements Xyz 
{ 
  @Override 
  public void doSomething(Param a) 
  { 
    throw new UnsupportedOperationException 
    ("A good explanation here"); 
  } 
  // Other method implementations 
} 
 

Alternatively, another option called comment asimplementation tends to be used, as shown in the following code: 

public  class Abc implements Xyz 
{ 
  @Override 
  public void doSomething(Param a) 
  { 
    // This method is not necessary here because of ... 
  } 
  // Other method implementations 
} 

The preceding examples successfully describe the problem that this principle was created to address. The best way to deal with this issue is by creating more consistent interfaces that conform to the other explained principles. The main problem with this issue is not related to having empty method implementations, but having additional functionality that is not used at all.

Suppose that an application depends on an XYZ library and the system is only using 10% of the available functionality. If a new change is applied to solve an issue that was present in the other 90%, that modified code represents a risk to the part that the application is using, even when it's not directly related to it.

The following questions will help you identify how well you are doing:

Please don't answer YES.

Hopefully not, as this will make it more difficult to implement all the abstract methods in concrete implementations. If you have many methods, please refer to the next question.

The method names should be consistent with the interface name. If one or more methods don't make sense at all, then a new interface should be created to place them.

If yes, go ahead and do it.

If the modules interacting with an interface are only using a few of the exposed functions, then the other ones should probably be moved to another interface, or even to new modules.

It is now time to define the dependency inversion principle:

Modules should depend on abstractions rather than on concrete implementations.

Abstractions represent the high-level details of a module, and the interaction among modules should be done at this level. Low-level details are volatile and ever-evolving. We previously stated that there are no problems with evolved modules, but of course, we don't want to break module interactions because of low-level details, and an excellent way to do this is to use abstractions rather than concrete implementations. The following questions will help you identify how well you are doing:

As discussed earlier in this chapter, many concrete implementations should have an abstraction in front of them. However, when it comes to one specific implementation, this is probably not the case.

The answer here should be no. Your framework or mechanism that is in charge of the dependency injection inside your application is responsible for doing this.