Recently, I got the impression that Ports & Adapters (PA)-style codebase structures have come under a lot of pressure. Reasons may be the various definitions found on the internet that make it hard to know which one to follow; the many port abstraction interfaces and associated mappings between core and outside world; or the class explosion per folder if the entire system only contains one core, data access, and presentation folder without further structuring into bounded contexts, “features”, or use cases.

Whatever the exact reason, in this article, I discuss what I think are elements of PA-style architectures that can be left out and on the other hand what elements are really advantageous to avoid unnecessary coupling to code and data that is not under our control.

It’s probably not conclusive so if you want to discuss further topics, just ask it in the chat :) Let’s get started!

If you want to get started on Hexagonal Architecture, check out my first blog post here:

Lose the Ports

A key problem with PA-style architectures is that they inherently come with what may feel like unnecessary abstractions - the ports themselves!

A port is a method signature that exposes either primitive data types or data structures from within. Such an approach essentially leads the “outside” of the hexagon to depend on the core of it, not the other way round.

Are these port interfaces actually needed? Not necessarily. The main idea is that the methods of the core hexagon don’t expose any outside data structures. If we simply follow this guideline and adhere to the dependency inversion principle, we don’t need port interfaces and instead can use the actual implementation directly.

The mapping does not disappear like that, unfortunately, but at least when traversing the application, we don’t have to awkwardly jump in and out of interface definition files.

What About Inbound Ports?

In my opinion, the last port I usually introduce is that of the inbound port. In most cases, there is only one implementation of that port and should it be replaced by a test double, it can easily be achieved by existing frameworks or vanilla inheritance.

Outbound ports may be reasonable especially when we want to replace an existing with a new one without the Hexagon knowing about it - but because an interface can be extracted in a blink of an eye, we may also wait this out until the actual need arises.

Simply adhering to the dependency inversion principle also in the implementation of the outbound adapter class avoids the need to add interfaces yet.

Service? Use Case!

I often see generic service classes implementing all the inbound port interfaces. That way, all the use cases are summarised in a single service for convenience. However, this makes it hard to split out cohesive, vertical use-case slices which simplifies their discovery.

If there is one contribution of Clean Architecture that solves this problem, in my opinion, it is the Use Case granularity of the hexagon core. One use case may contain a couple of (private) methods, but only the actual use case method is invoked by a controller. This increases cohesiveness and reduces coupling from unrelated use-case methods.

Should we provide only one controller for all the publicly exposed API methods, at least we can structure the application core simply by different use case classes. We don’t even need additional folders anymore within that application folder to separate the use cases. Use cases become first class citizens in this screaming, domain-centric architecture.

If we additionally apply the idea from before and leave the inbound ports out, the controller’s member variables basically stay as expressive as before, but navigating the code is simplified.

Vertical Use Case Slice?

A next natural step from the above idea is to create a controller per use case. This also makes sense from a cohesion point of view. That means the following:

But now we have to ask ourselves what we gain from the additional abstractions if we always have a controller- and use-case pair. We are basically back to Onion Architecture’s “CustomerController”, “CustomerService”, now on a use case granularity. So naturally, we could just inline the entirety of the use case into the controller:

And inject the adapters for databases and external systems directly. And maybe even rename the controller to use case?

We may have to adjust transaction boundaries and move them from the use case method to the controller method instead. But else, there is actually nothing wrong with such a setup. We basically have arrived at a vertical-slice architecture.

Any repository or surrounding system can directly be called from the controller/use case. Because data-access classes may be used with various use cases in the same bounded context, we can add them to an external data access folder within a bounded context (or move it even outside into a shared module if other bounded contexts need to access it, too).

So the structure may look like:

app 
|_ shared_data_access
|_ bounded_context_1
|_ bounded_context_2
  |_ use_cases
    |_ CreateXUseCase
    |_ CreateYUseCase
  |_ data_access
    |_ ExternalSystemAdapter
    |_ ExternalSystem

Which flattens the traditional modules to use cases and data access.

Dependency Inversion? Anti-Corruption!

I’d keep dependency inversion on the outbound side even if no outbound ports are employed. A simple adapter class can map between use case and external system. I feel this mapping is important to avoid coupling with an external system or database that may not be under our direct control. The adapter effectively becomes an Anti-Corruption Layer.

If the data access is under our control, we may even leave out this external system adapter and directly access the database or repository connector. In any case, I recommend to separate data-access logic from business logic even if the code remains rather procedural.

If that proofs too difficult to achieve within one team, separating the two concerns using abstractions like classes and functions with own data structures can simplify maintainability.

No Architecture At All?

Let’s face it: most of the code we create is not rocket science. We basically move data from A to B, with a bit of logic for manipulation in between. The important separation is that of the 3 concerns presentation, business logic, data access.

The data we present to the user may not be the same as the one we need for business calculations, and the data access may store different fields again for optimisation reasons. This is often true for command-like operations, meaning use cases that change a state. So having 3 different data representations may actually proof reasonable, except when we simply map the same fields between different concerns.

On the other hand, query-like operations (getters) can provide precomputed views that don’t require any mapping at all. Having additional data structures for core and adapters, where we map the same data items multiple times without any logic in between, is a maintainability nightmare. Here, PA-style architectures are simply in the way of maintainable software.

If team members have mastered this logical separation between data access, presentation, and business logic (which doesn’t take longer than a couple of weeks of active practicing), they should be able to decide on a use-case basis how much abstraction is actually needed.

A Final Word

Software Architecture, even if only used within a Modulith to structure low-level code, is still architecture. This means we need to make architectural decisions: we need to weigh pros and cons of every decision against each other with incomplete understanding and information.

This also means that we sometimes get it wrong. There is simply no silver-bullet solution template that we can apply to every software design problem, even though I feel that many software engineers want exactly that.

Instead, we need to be aware of all the possibilities we have to structure our code, be it all inlined procedural code per use case or full-blown Clean Architecture (which, in my opinion, generally will be too over-engineered), how to identify and resolve problematic software design, and how to quickly move from one design to another, either through manual refactoring or well-formed prompts if we want to give AI a shot.

This is hard. And the more we practice, the better we become. Instead of pretending we know everything, we should work together and leave our ego at the door. Every idea and decision has pros and cons, and some may be better suited than others. But most ideas are not absolutely wrong.

If the software works according to specification or user feedback and is simple to change with no to few bugs, the design is the right one, regardless of how much Ports & Adapters was applied or not.

We need to judge design according to our ability to create, change and maintain it cheaply, not on “how it looks like”. Only then will we create software that actually solves the problem of their users. And only then will they come back to us and ask for more.

Want to learn more?

Curious to go deeper?

Our O’Reilly course “DDD, EventStorming, and Clean Architecture” covers in detail how to get from a Layered- to Hexagonal-, Clean-, and even Vertical-Slice Architecture and the pro’s and con’s of each approach.

This overview will equip you with the theoretical and practical knowledge needed to guide your AI assistant into the right direction during development and avoids creating a procedural mess in the process!

We also provide remote, hybrid, and on-site workshops on Software Design and Architectural Design Patterns like Hexagonal- and Vertical-Slice Architecture which you can find on our website - codeartify.com.

Check it out!

Why So Many Sticky Colours?

The full set of stickies used in both EventStorming and Event Modeling can feel overwhelming in the beginning. But especially if the goal is to start exploring a problem domain with everyone involved (like developers, business reps, stakeholders), all we actually need are Domain Events.

The best discussions often emerge when we start jotting down what we believe is happening in the domain using Domain Events, placing them on a Timeline that shows which event comes after which. That’s it.

These discussions naturally surface misunderstandings and help align everyone’s mental model. This alone can massively improve collaboration and reduce friction once development starts.

We should only introduce more stickies if there's a clear need. The logical next stickies are Actors and External Systems, since someone or something needs to trigger those Domain Events.

What is a Domain Event?

A common source of hesitation is the term "Domain Event" itself. Workshops often start with something like, “Let’s collect all the events that can happen in our domain.” But this can immediately raise questions like: “What do you mean by an event?”, “Why are we talking about things in the past?”, or just a general “This feels weird.”

It’s not always easy to explain what a Domain Event is. But here’s something that’s worked well for me in many cases: a Domain Event represents something meaningful that has already happened in the business domain. It’s something that the system (or others) might want to react to.

For example: A user submits an address form. After the address is successfully stored, we publish an event like “AddressSubmitted” to inform other parts of the system what happened. That’s a Domain Event.

Of course, not every Domain Event needs to involve a state change, but thinking of them as the result of some meaningful outcome helps people get started.

Use Domain Language, not CRUD

We’re all conditioned to think in CRUD terms: Create, Read, Update, Delete. But when we model using Domain Events, that mindset gets in the way.

Even business stakeholders might talk in CRUD terms because they've absorbed our technical language. That’s why we need to be intentional about using the domain’s own language during these workshops.

Take “AddressSubmitted” for example. A CRUD mindset might have started with Domain Events named “AddressCreated” or “AddressUpdated.” But such names lose important context. If someone updates their address because they moved, why they moved might affect what the system needs to do next.

A concrete example might be a Swiss tax system. Here, different rules apply depending on whether someone moved within the same municipality, to another one, or abroad. So instead of just “AddressUpdated,” we might model each Domain Event separately as:

• MovedWithinMunicipality

• MovedToAnotherMunicipality

• MovedAbroad

This makes the system clearer, more explicit, and easier to evolve.

Domain Events for Different Granularities

Sure, we could just emit a general “AddressUpdated” event and let downstream systems figure out whether it was relevant for them or not. But that leads to unnecessary complexity and wasted computation. Having more explicit Domain Events generally keeps things cleaner and more maintainable.

The granularity of Domain Events isn’t a hard science. It depends on your domain, your team, and how the system is supposed to behave. The key is to let the discussions guide the granularity, and be okay with evolving it over time as your understanding deepens.

Event Modeling / Storming is Agile

In general, these workshops are not meant for Big Design Up Front. They work best when used with an agile mindset: increment → feedback → iterate.

We want to collaboratively build a shared mental model of the business domain. There are no absolute “rights” or “wrongs.” Each round of discussion improves the model.

The more questions we raise during an initial session, the better. They signal gaps in understanding, which are perfect opportunities for exploration and experimentation.

These models are lightweight and often inaccurate in the beginning. But that’s fine. Real clarity tends to emerge once implementation starts, iteratively.

Some teams have tried using these techniques to plan 3 years of development in advance and were disappointed with the result. That’s not surprising as it contradicts the agile spirit these workshops are built on.

LLMs in Collaborative Workshops

One final note: I do believe that AI tools like LLMs can actually support a more iterative and collaborative approach.

They let us cheaply experiment with ideas, generate working examples, and validate flows without needing to build full mockups that rarely reflect real product behaviour anyway.

Even better, consulting LLMs regularly helps speed up decision-making. We no longer have to awkwardly piece together everyone’s fragmented knowledge but can use AI as a thinking partner to get clearer, faster.

This is one of the most exhausting parts of traditional workshops: everyone trying to explain their fragmented understanding, often in inconsistent ways. LLMs might help bridge those gaps if used thoughtfully.

I’m genuinely hopeful that AI will improve how we collaborate and ultimately lead to better software that solves real problems, faster and cheaper.

Let’s see where it takes us :)

Want to learn more?

Curious to go deeper?

Our O’Reilly course “DDD, EventStorming, and Clean Architecture” extensively covers both Big Picture EventStorming and Design-Level EventStorming for you to get started with the topic in more depth.

We also provide remote, hybrid, and on-site workshops on EventStorming, either exclusively as a deep-dive or integrated into the wider context of collaborative software development.

Check it out! :)

Approval Tests is a library that makes it very easy to automate that task. It provides CombinationApprovals: for every defined input parameter, the library automatically creates every combination of them, easily covering a multitude of test cases with a single test.

I will show here how to install and apply it to your codebase, and some pitfalls to avoid when setting it up.

Approval Testing

The basic idea of combinations approval testing is the same as described in my article on manual approval testing:

There are 5 steps to manually writing Approval Tests (DAAARt 🎯):

1. Define: what method should be tested

2. Act: call the method under test

3. Arrange: add missing dependencies

4. Assert: the state of affected object as string

5. Run test coverage: to see what branches have not been covered yet

Installing the Library

Builds can be found for a variety of languages. I’m using the Java Maven dependency for these examples:

<dependency>
    <groupId>com.approvaltests</groupId>
    <artifactId>approvaltests</artifactId>
    <version>24.17.0</version>
    <scope>test</scope>
</dependency>

Understanding the Library Function

I use the following codebase. Like in the previous article, I will create an approval test for the outermost controller method:

ParkingSpotReservationController::reserveParkingSpot takes a ParkingSpotReservationService as a constructor input and ParkingReservationRequest as a method parameter.

Let’s create a usual Unit Test for it:

The method I’m interested in is CombinationApprovals.verifyAllCombinations(). This method takes 2 types of inputs:

1. The method to test as a Function

2. 0 - N input parameters into that method, each represented as InputType[]{}

The arrays for the input parameters allow the framework to automatically generate all combinations, increasing coverage. We don’t need to manually consider every possible input combination anymore.

Creating a Testing Function

Let’s create the Function to pass to verifyAllCombinations. The behaviour we want to fix in place is the following:

ParkingSpotReservationController takes 1 service argument in it’s constructor and 1 request argument in the reserveParkingSpot method. A first approach could be to create a function that passes these two parameters and returns the response, like:

However, we don’t want to stub the ParkingSpotReservationService, which is the argument passed to ParkingSpotReservationController. Like with manual approval tests, only awkward, meaning hard-to-instantiate, slow, or nondeterministic dependencies should be stubbed. So we instantiate the service inside that function as-is and pass it to the controller.

The two dependencies passed to the ParkingSpotReservationService are indeed such awkward dependencies. They are framework-specific JPA repository interfaces (ParkingReservationRepository and ParkingSpotRepository) and should be stubbed and passed to the method:

Now one issue remains: the returned ResponseEntity<Object> class only has a framework-specific toString() method that we cannot predict what it will return.

To counter that, as with manual approval tests, we create a static stateAsString method that retrieves only those fields we are interested in. This method will be the state that we want to save to fix the behaviour in place:

The final function to pass to verifyAllCombinations is therefore going to be:

It can now be used as a static function call like:

ParkingSpotReservationControllerApprovalTest::createAssertableOutput

Creating a Test

The simplest test that runs through with an empty output looks like the following:

As a result, we get two output files:

These two output files are currently empty. Once we add working parameters in their respective arrays, these files will contain either the output to assert (received.txt) or the approved output (approved.txt).

If we run the test again without changing anything, the received.txt file will disappear because we “approved” that empty output is the state to fix in place, and the test becomes green.

First Output to Assert

Now we need to apply DAAARt (see above), So let’s check the code and arrange the dependencies to test to cover as much of the code as possible per test.

The first test case that gets into the body of the service and covers as much code as possible can be achieved by creating two stubs for the awkward repository dependencies, one that returns no active reservation, and one that finds an empty spot. Plus, the requested reservation period needs to be within operating hours and at least 30 minutes long. This results in the following code:

I intentionally override the toString methods of the two repository stubs and return exactly what their purpose is, withoutActiveReservation and findSpot because it makes it easy to see in the output what test case was covered:

If we use IntelliJ, we can now simply press the » button in the middle of the screen and add the new parts to the approved.txt file.

Now, the contents are identical, and if we run the test again, it becomes green and the received.txt file disappears.

Let’s also investigate the test coverage now (see the other article to learn about viewing test coverage):

With this 1 test alone, we covered already 74% of all lines of code. By exploring the code first and choosing the input parameters reasonably, we can quickly cover a large portion of the code.

Automatically Testing Parameter Combinations

If we now add 2 additional parameters, for example two repository stubs for “withActiveReservation” and “findNoSpot”, we get the following output:

Now we got 4 (1*2*2) input combinations because the library recombines them all.

How convenient. In manual approval tests, we would have had to write a test for each combination or use a parameterised test, but even then we would not have received an output that is that easy to update like with received.txt and approved.txt.

Quickly Covering Lots of Ground

Let’s try to cover all the branches. With 4 requests, 2 reservation-, and 2 spot repo stubs, we can create 4*2*2 = 16 combinations in 10 lines of code.

By using this framework, we can be sure not to miss combinations like we could with manual approval tests. Even though at the moment some cases may not be relevant, as soon as we start refactoring, we could create code that could

Handling Issues with Line Breaks

Depending on the IDE used, it may happen that even though the result of the approval tests didn’t change, the IDE appends a whitespace after each line. In IntelliJ, this can be avoided by using the following line in the .editorconfig:

trim_trailing_whitespace = false

Example

See the full example in the following video:

Conclusion

I have demonstrated how CombinationApproval can fix a method’s behaviour quickly in place, much faster than doing it manually using manual approval tests, while simultaneously combining all the parameters to create more test cases.

With these tests in place, we can be more confident when we make changes to the code that it will not break.

Another important technique that can help us finding uncovered combinations is called Mutation Testing. In a next article, I will explore what it is and how to apply it, and how it can be used in Legacy applications to improve confidence in test coverage even more.

Resources

To get rid of the yellow test name, you can change the test name pattern in IntelliJ to

[A-Z][A-Za-z\d]*(Test(s|Case)?|Should|TestShould)|Test[A-Z][A-Za-z\d]*|IT(.*)|(.*)IT(Case)? 

in the following menu:

To effectively refactor Legacy code, we need to have a specific goal towards we want to move our design. Our O’Reilly course “DDD, EventStorming, and Clean Architecture” can help with that, as it introduces Domain-Driven Design and how to implement Aggregates in Hexagonal and Clean Architecture.

If you want to learn how to effectively separate concerns in Legacy code and move your application towards a better design, you could also have a look at our on-premise, remote or hybrid workshops Modern Software Architecture Design Patterns and Untangle Your Legacy Code with Domain-Driven Refactoring, where we dive into the presented topics in much greater detail.

To effectively learn how to identify code smells and refactor them, check out our workshop on Clean Code.

Refactoring means changing the internal structure of the code without changing its observable behaviour to make it easier to understand and cheaper to modify (Martin Fowler).

We thus need to refactor code continuously to remain able to save or make money for our business. If maintaining or changing our code makes us lose money, refactoring it can have many advantages over rebuilding it from scratch as the business knowledge is already there, it just needs to be brought back to light.

However, to be able to refactor code effectively without potentially introducing bugs while doing so, we need a strong set of effective and preferably fast, tests.

Legacy code typically lacks sufficient test coverage to refactor effectively. If it had, it would not be considered legacy code, as it would allow for frequent, cheap changes.

Thus, we need a way to test legacy code without falling into analysis paralysis or potentially introducing bugs while improving its design.

A proven solution to this problem are so-called Pin-Down-, Characterisation-, or Approval Tests: quickly written, fast throwaway unit tests that pin the current behaviour in place while avoiding the mental overload and structural problems of writing “real” unit tests for legacy code.

This test harness then becomes the insurance for refactoring the code and improving its design incrementally, avoiding costly rewrites in the process.

In this article, I want to focus on writing Approval Tests manually to understand the concept and have a technique at hand that requires no additional dependencies, which can be useful for small legacy methods.

In future articles, I will introduce some useful libraries that build on this knowledge but automate a lot of the manual steps, helping pinning down behaviour of larger legacy methods with lots of input parameter combinations.

Testing Legacy Code with Approval Tests

You can try it out yourself in the following codebase.

There are 5 steps to manually writing Approval Tests (remember DAAARt 🎯):

1. Define: what method should be tested

2. Act: call the method under test

3. Arrange: add missing dependencies

4. Assert: the state of affected object as string

5. Run test coverage: to see what branches have not been covered yet

Defining Appropriate Methods to Test

We want to start as far out as possible, for example with a REST controller or a use case service method, so that we cover as much code as possible with one test and don’t end up tying our code to our test. This means many classes may possibly be tested together.

I typically create a unit test that ends in “ApprovalTestShould” to indicate its purpose, for example ParkingSpotReservationApprovalTestShould.

Acting and Arranging

We start by creating a unit test that simply instantiates the class containing the method, and pass all parameters to the constructor or method as null.

Then we run the test. This inevitably will lead to null pointer exceptions (NPEs) and other errors, which we need to fix, typically by injecting the required dependencies step-by-step.

We choose to inject as much production code from our own codebase as possible, and only resort to injecting test doubles (“mocks”) for awkward dependencies.

Awkward dependencies are those that are slow or non-deterministic. Typical examples include:

• I/O

• Database

• Filesystem

• Random Number Generator

• Time

We continue acting and arranging, which I like to refer to as “sledgehammering our way through the code”, until we reach the bottom of the code and the test runs through without errors and becomes green. Naturally, it’s only green because we do not assert anything yet. This changes in the next step.

Asserting with stateAsString()

We assert the state of the object under test, or whatever object the method returns, as a simple string.

We can either use the toString method if it contains the entirety of the state, or write a dedicated stateAsString method on that object to indicate that this method is only intended for Approval Testing.

In general, I’d recommend using the dedicated stateAsString method not to interfere with changes that may get introduced along the way to official toString methods.

A stateAsString method could look as follows:

String stateAsString() {
    return "name: " + this.name + ", age: " + this.age + ";
}

If we cannot define a stateAsString() method on the result value because it is a framework-specific class, we can still create it inside the test class as a static method:

private String stateAsString(ResponseEntity<Object> result) {
    return "body: " + result.getBody() + 
           ", "status code: " + result.getStatusCode();
}

Initially, we don’t know yet what the stateAsString() method will return. This is why we start by simply asserting an empty string against the state as a string:

assertEquals(“”, unitUnderTest.stateAsString());

This will inevitably lead to the test finally failing for the right reason. We want that to happen: we can now simply take the output of the test comparison as is and place it in the empty string of the assertion method.

assertEquals(“name: Olly, age: old”, unitUnderTest.stateAsString());

Now we run the test again and it will pass.

Running Test Coverage

The final step before the cycle repeats is to run test coverage and see how much code was covered by that test. We always try to cover as much code in one go as possible. Test coverage can be found in IntelliJ e.g. if we click on the 3 dots next to the “run” button:

You also need to make sure that all the packages for which coverage should be shown are included in the test configuration:

Once we run these tests with coverage, we can find on the left side 3 colours indicating coverage:

• green: covered by tests

• red: not covered by tests

• yellow: covered at least once, but not with every possible combination.

Our goal is to get to cover as much as possible, or have a good understanding why some parts of the code are still yellow or even red (e.g. due to unreachable code).

We get additional information about class, method, line, and branch coverage in the window that opens when we run coverage, as can be seen in the following screenshot:

Any branch not covered by a test becomes the target for the next test. We simply adapt a couple of parameters to reach those branches without losing too much brain capacity to think the algorithm through, and repeat the DAAARt coverage cycle until we are confident enough that our tests cover enough to be able to start refactoring.

Example

In the video below I show how to write a first manual Approval Testsuite, step-by-step. You can find the solution on the branch manual-approval-testing in the codebase.

Combinatorial Explosion

It is a good idea to practice such a manual technique in order to have it ready should you encounter an untested legacy method and need to refactor and extend it without breaking it in the process.

However, a method with lot’s of input parameter combinations can make it very cumbersome to cover all the branches with tests. That is why tools like ApprovalTests exist. In a future article, I will show how to employ this tool too.

It builds on the same ideas introduced here, so it’s a good idea to practice the concepts first before moving to such a tool.

Conclusion

Testing legacy code is not trivial. By employing Approval Testing, we can circumvent the issues of analysing code by simply asserting whatever the code returns, and then mutating input values until we covered all branch combinations.

These tests form the basis for further refactoring endeavours by providing an effective safety net that can be kept for the entire time of the legacy code rejuvenation.

Just remember the 5 steps involved: DAAARt 🎯

1. Define which method to test

2. Act

3. Arrange

4. Assert

5. Run test coverage

In a next article, I will show how to employ libraries to streamline the process of writing Approval Tests.

Resources

To get rid of the yellow test name, you can change the test name pattern in IntelliJ to

[A-Z][A-Za-z\d]*(Test(s|Case)?|Should|TestShould)|Test[A-Z][A-Za-z\d]*|IT(.*)|(.*)IT(Case)? 

in the following menu:

To effectively refactor Legacy code, we need to have a specific goal towards we want to move our design. Our O’Reilly course “DDD, EventStorming, and Clean Architecture” can help with that, as it introduces Domain-Driven Design and how to implement Aggregates in Hexagonal and Clean Architecture.

If you want to learn how to effectively separate concerns in Legacy code and move your application towards a better design, you could also have a look at our on-premise, remote or hybrid workshops Modern Software Architecture Design Patterns and Untangle Your Legacy Code with Domain-Driven Refactoring, where we dive into the presented topics in much greater detail.

To effectively learn how to identify code smells and refactor them, check out our workshop on Clean Code.

Uncle Bob’s Clean Architecture adds additional rules and nomenclature to the Hexagon. In this article, I want to explore the commonalities and differences and how we can easily move to from Hexagonal to Clean Architecture.

Hexagonal Architecture

Let’s recap the basic Hexagonal Architecture components:

The hexagon can effectively be divided into outside- and inside components.

The inside of the hexagon contains the actual application. This can be a service method. It communicates with the outside world through ports, which effectively are interfaces that contain either primitive types or types defined within the app. No outside dependencies can be found in the app. It is typically devoid of any framework dependency.

The outside of the hexagon can be divided in driving and driven sides depending on which side of the diagonal they are. Driving adapters use (inbound) ports to map data from an outside source to the internal format of the app, and call (drive) the app through that port. If we practice TDD, the first driving adapter is going to be a test.

On the driven side, we can distinguish between repositories, which are data-access and -storage units to which an application can read to and write from using (outbound) ports. These are bidirectional accesses, so the app can also receive updates from these adapters.

On the other hand, also unidirectional messaging adapters exist that can simply be referred to as recipients. These recipients can be fire-and-forget queues or emails, or also a website that receives the view model.

Importantly, driving adapters use ports to invoke an action on the app, while driven adapters implement the port interfaces and are called by the app through those interfaces. This effectively is a combination of dependency inversion and interface segregation, placing the business app into the center.

From Hexagonal- to Clean Architecture

Clean Architecture builds on Hexagonal Architecture by providing some additional rules and nomenclature to it. The main idea however is exactly the same - separate business concerns from outside presentation- and data-access concerns. It’s a bit like applying certain DDD concepts onto the Hexagon, even though Uncle Bob never really mentions DDD in that context for whatever reason. Let’s see how it compares.

I intentionally kept some of Hexagonal Architecture’s building blocks even though the typical Clean Architecture diagram uses circles to emphasise that if you know how to hexagon, you easily get how to clean:

Use Case instead of “App” or “Inside”

While Hexagonal Architecture stays (intentionally?) vague about the size of the inside of the app, Clean Architecture emphasises a “use case” split. A typical use case could be ReserveParkingSpotUseCaseInteractor or similar business-domain actions, which typically are single application-service methods.

Uncle Bob uses “Interactor” for the implementation names because the inbound port interfaces are named “UseCase”, e.g. ReserveParkingSpotUseCase.

I personally prefer to name single method interfaces as actions, so my interface name would be ReserveParkingSpot, while the actual implementation would be ReserveParkingSpotUseCase. But that’s up to the author of course.

However, the idea of having a set of first-class citizen use cases heavily improves discoverability inside the codebase.

Imagine talking the same Ubiquitous Language as business stakeholders and easily searching and finding these use cases quickly inside the codebase without having to skim through large generic services with many methods.

Use Cases also add a great domain-driven granularity to the hexagon, making them perfectly suited to be grouped into DDD bounded contexts as these quotes from Learning Domain-Driven Design by Vlad Khononov imply:

Creating Modular Monoliths / Moduliths may be simplified by identifying use case interactors that belong together and grouping them into a single module, effectively creating a starting point for a domain-driven bounded context.

It all seems to come together with the introduction of use case interactors!

Use Cases have the same tasks as DDD’s application services as they are application business rules. In general, they check global validation, load, update, and store entities, and present the result to the outside world through so-called presenters.

Entities

While Hexagonal Architecture does not specify the internal structure, Clean Architecture adds Entities. Entities represent the critical business rules of an application and could be used in a wide variety of use cases across the company.

From that description, they basically fulfil a similar role as value objects and entities of the DDD domain model, but Uncle Bob is less precise about it.

We can see that while Hexagonal Architecture has no definition of how the inside of the hexagon should look like, Clean Architecture at least knows entities. But if you want to be precise with the implementation, then the clearest distinction is to use a DDD domain model as the most internal part of the application, which is also how it is described in Vaughn Vernon’s implementing DDD.

I personally always use a domain folder instead of an entities folder, even when implementing Clean Architecture, and distinguish between entities and value objects even if I don’t use a fully blown Domain Model with aggregates.

Controllers

Taking the name from Model-View-Controller MVC, Controllers act as driving adapters that map the input from some view, like a console or web view, to the format the use case requires, and invoke that use case interface.

Depending on the technology used, Controllers may also be responsible to ensure the output of a use case returned to the view model again. I will show in a follow-up article what I exactly mean by that.

Gateways

While Hexagonal Architecture distinguishes between Repositories and Recipients, Clean Architecture only knows Gateways. However, these ports and their respective implementations have the exact same purpose and therefore can be uni- or bidirectional, depending on what data they transfer.

Presenters

Presenters are specialised ports with respective adapters that do not explicitly exist in the world of Hexagonal Architecture, but could be considered specialised Recipients, meaning unidirectional ports/adapters to the view.

Their purpose is to map between the result of a use case to the respective view model. This means that both success and error cases need to be handled, often leading to at least two ports for presenting them.

The view model created by presenters should be extremely specific. For example, they should specify the color of a button or font to display, such that the frontend simply fills the values from the backend into the required fields. I have yet to see such an implementation in real life, though.

Crossing Boundaries

While Hexagonal Architecture does not specify the data that crosses boundaries except that the outside needs to depend on the inside and not the other way round (or be agnostic if primitive types are used), in Clean Architecture, only very simple primitive types, simple data structures like hash maps or DTOs can be used for that purpose.

That means that gateways do not return entities. Entities are built within the use case. Even though I understand the reason behind it, as I described in this article, I typically follow a more pragmatic approach and return DDD aggregates through these data-access ports to reduce the number of mappings as they can significantly slow down the application.

Similarly for the inbound ports, I usually use value objects from the domain model to cross boundaries for the same reason. Clean Architecture would do the mapping and validation inside the use case itself.

Conclusively, if you want to comply 100% with Clean Architecture, you would map a whole lot more between the different concerns than might actually be necessary. It depends on the use case if that is actually really needed, for example if the use case objects should be shared among various teams without exposing their internal structures.

Conclusion

I have discussed the commonalities and differences of Hexagonal- and Clean Architecture.

The main contribution is to split the inside into use case parts. This is a great perspective to build any domain-driven application from, as a couple of use cases together can form a bounded context, which helps modularising applications.

Clean Architecture contains an entity concern at its core, which is a great place to put a DDD domain model into. Such a core is not specified by Hexagonal Architecture.

More specific rules for ports and adapters like Controller, Gateway, and Presenter add additional clarity, but need to be evaluated on a case-by-case basis which make sense and which do not.

Data structures used in ports should be simple - only primitive types, Hash Maps or DTOs should be used. No entities should cross the borders, even for database gateway adapters, which means possibly more mapping between the concerns.

In a next article, I will show how to move from Hexagonal- to Clean Architecture with an example, so subscribe if you don’t want to miss it:

Subscribe now

Resources

This article is part of a series moving towards a business-centric architectural design. See the following post to get started.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on exactly these topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture in one single course.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns. To effectively learn how to identify code smells and refactor them, a core skill needed to transform your application to Hexagonal- or Clean Architecture, also check out our workshop on Clean Code.

In this article, I want to illustrate what works for me and what I have employed in projects already. This means it’s an opinionated article, and others may structure it differently. Take it as a source of inspiration, and then adapt it to your personal needs.

Basic Folder Structure

The basic folder structure of a hexagonal architecture in my projects should always somehow separate the inside from the outside, or the core from the adapters.

Therefore, a perfectly viable, simple structure could be:

app_name
|_outside
|_inside

or

app_name
|_adapter
|_core

Depending on the complexity of the application, app_name can represent

• the entire application (all the business use cases),

• a DDD bounded context (sub-domain-related business use cases),

• a single narrow, vertical business-use-case slice,

• or any other business-driven decision to split up the application,

as long as the slice represents a vertical, business-driven whole, and not some technical, generic, domain-agnostic concept or horizontal split like “presentation”, “data_access”, “application”, “domain”. The latter splits will find their places inside each vertical business slice, if useful.

Inbound vs. Outbound

If we continue with the “core” vs. “adapter” names, we can also introduce a port folder inside the core which makes it easy to see how we can interact with the application.

An additional useful separation inside the adapter and port folder structures can also be to separate them into “in(bound)” and “out(bound”). That way, we already see that in ports can only be used with in adapters, and out ports with out adapters.

app_name
|_adapter
  |_in
  |_out
|_core
  |_port
    |_in
    |_out

Depending on the kind of adapters employed, it can make sense to add additional information to the adapters that specify what kind of technology they employ. For example, if the inbound adapter is a REST resource, we can add “web” to it. Similarly, when we have in-memory and sql data-access repositories, we can add that to the out folder as well:

app_name
|_adapter
  |_in
    |_web
    |_...
  |_out
    |_in_memory
    |_sql
    |_...
|_core
  |_port
    |_in
    |_out

Don’t use technology-specific names for port folders! They are inherently technology-agnostic and therefore should not mirror exactly the adapters’ folder structure besides the in/out parts.

Domain-Driven Design Folder Names

Alternatively, or additionally, we can also employ language from Domain-Driven Design in our folder structure.

For example, we can add a presentation folder to the in, and data_access to the out. This can become helpful especially when we add other “out” adapters, for example for sending messages, emails, or other uni-directional recipients that are not direct data access.

The core additionally contains the application, and we could move the ports inside of it, indicating them to be part of the application concern.

Furthermore, if we employ a domain model, we can add an additional folder called domain that can be placed inside the core. I wouldn’t place it inside application however as it represents a separate concern after all.

app_name
|_adapter
  |_in
    |_presentation
      |_web
      |_...
  |_out
    |_data_access
      |_in_memory
      |_sql
      |_...
|_core
  |_application
    |_port
      |_in
      |_out
  |_domain

In case we need more structure, an additional folder separating values and entities could be added to the domain. Aggregates would become part of that entities folder, or we can add another aggregates folder.

app_name
|_adapter
  |_in
    |_presentation
      |_web
      |_...
  |_out
    |_data_access
      |_in_memory
      |_sql
      |_...
|_core
  |_application
    |_port
      |_in
      |_out
  |_domain
    |_values
    |_entities

The in- and out folders in the adapter folder, and the core folder may become overly nested here and as an alternative, we could simply have the three main folders adapter, application, and domain inside the app_name.

app_name
|_adapter
  |_presentation
    |_web
    |_...
  |_data_access
    |_in_memory
    |_sql 
    |_...
  |_...
|_application
  |_ports
    |_in
    |_out
|_domain
  |_values
  |_entities

As a consequence, my typical high-level folder structure typically looks like:

app_name
|_adapter 
  |_presentation
  |_data_access
|_application  
|_domain 

and then I add or split as the application grows. I like this structure because it honours separation of concerns, Hexagonal Architecture, and Domain-Driven Design, while avoiding an overly nested structure.

Don’t rack your brain over it. If you don’t need a folder, simply leave it out.

Illustration

The diagram above shows the codebase introduced in the last articles. I left it in an unfinished state regarding its folder structure. This is what I’m going to change now. I choose the following structure:

parking_spot_reservation
|_adapter 
  |_presentation
    |_dto 
  |_data_access
    |_model
|_application
  |_exception
  |_port
    |_in
    |_out
|_domain
  |_entity
  |_exception 
  |_value

I chose the presentation / data_access / application / domain structure because we immediately find the different concerns and it helps with incorporating domain-driven concepts easily. presentation and data_access are both part of the adapter package.

I take over the dto and model packages from the original structure and add it to the presentation and data_access packages, respectively, but that’s completely optional.

If we work with exceptions, it also makes sense to separate application-specific exceptions, which are thrown only from the service, from those thrown e.g. from a domain value object creation like ReservationDetails. Two additional exception packages in both domain and application folders helps organising them.

I place Reservation, the only possible DDD aggregate in that example, into the entity package. If the application grew without further splitting, an aggregate package may be added as well to highlight the interaction points for the application service, but that would be overkill just now.

The colours indicate the different concerns (red = data_access, orange = presentation, lilac = application, light blue = domain).

You can find the example solution on branch package-structure in the codebase.

It’s important to note that the package structure should be as flat as possible as too much nesting can impede navigation and add more complexity than needed. It is always a tradeoff between more structure and a harder to navigate codebase.

There is no one-size-fits-all solution when it comes to package structure. Every use case needs to be reevaluated. But the high-level structure of adapter-application-domain, with an additional separation of the adapter package to presentation-data_access, provides a great way to start from.

Conclusions

Different possible package structures exist to organise a Hexagonal Architecture depending on its complexity. A reasonable approach separates inside from outside, or core from adapters.

If we incorporate the 4 different concerns, we additionally add clarity where to put what. The core can be divided into application and domain, the adapters get two additional packages presentation and data_access.

The highest level folder can be the entire application or smaller bounded contexts or even use cases. It always depends on the complexity of the application.

We need to avoid overly complex nested structures as these can hinder quick navigation. It is always a trade-off between more structure and easier access.

Resources

This article is part of a series moving towards a business-centric architectural design. See the following post to get started.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

To effectively learn how to identify code smells and refactor them, check out our workshop on Clean Code.

In this article, I want to illustrate how to find logic in a codebase and move it to the domain model.

Identifying Logic for the Domain Model

Currently, all the domain model classes contain no logic at all and are therefore anaemic data classes, a code smell in OOP.

An indication for displaced logic that should be moved into the domain model can be found when we investigate which classes access the getters from that anaemic domain model to perform some logic like validation, formatting, or more complex manipulations on that data.

Depending on the context and concern these classes are defined in, such direct data access can be considered a code smell called Feature Envy, meaning that a class is envious of the features (e.g. data, state) another class provides. This access creates a tight coupling between the two classes.

To increase cohesion and reduce coupling, the logic applied on that data can often be isolated in an own method and moved to the accessed class, as shown below.

In procedural code, we often first need to untangle some cohesive logic and extract it into a separate method before moving it from the envious to the accessed class.

What we can typically see as soon as we extract a method containing the accessed class is that the accessed class is part of the parameter list of this method.

Such parameter objects are possible targets to move the method to, especially if there is only one parameter.

Honour the Concern- and Dependency Rules!

Before we move methods into other classes however, we need to be careful not to break concern- and dependency rules.

Logic should mainly be moved around within a concern. As soon as we cross concern boundaries, we risk that logic ends up in the wrong place.

For example, presentation logic should not all of a sudden end up in the business concern just because the presentation controller adapter accesses many fields of an application-concern data structure or domain model to create its output JSON.

The same is true about moving translation logic from the data-access concern into the hexagon’s core. The domain class should not know how it is translated to a DB entity and thus, this logic should remain within the data-access adapter.

For our purpose of creating a rich domain model, this means that logic can only be moved from the application concern into the domain model.

Example Refactoring

Validation Logic in the Service

Let’s have a look at the following code snippet taken from the codebase:

We see a lot of logic to ensure that the ReservationPeriod is in a valid state before we can process the reservation request any further.

This piece of logic does not require and additional call to another system and can be done completely in isolation. All it does is accessing the ReservationPeriod’s startTime and endTime. It is therefore a great candidate to be moved into the actual ReservationPeriod class.

In fact, we could restructure the code a bit to validate startTime and endTime when we create the ReservationPeriod. The following video illustrates this refactoring.

1. Start by temporarily extracting startTime and endTime into separate local variables so that the code block does not contain any strong type anymore.

2. Wrap the constructor of ReservationPeriod into a static creation method such that we can only create a new ReservationPeriod through that method.

3. Copy-paste the logic into that creation method (together with any constants defined in the service class that are only accessed by that logic).

4. Remove the logic from the service method.

We can further improve the creation methods readability by solving the Complicated Boolean Expression code smells through the introduction of two intention-revealing static query methods, shorterThanMinimalReservationDuration (and rename the corresponding exception), and outsideOperatingHours, which allows us to remove the one-line redundant and obsolete comment code smells that were present before:

Trade-Offs of Domain Model Classes in Port Interfaces

However, now we have a bit of am issue that we need to take care of: we need to mitigate the risk of exceptions being thrown outside the try-catch block in the calling controller class:

This is one of the trade-offs of exposing complex domain model classes in port interfaces. Even though we can spare one translation step by avoiding an additional application-specific port DTO to map to and from, we now need to take care of the correct error handling outside the hexagon.

We could also have saved one translation step if we used the presentation concern’s request DTO inside the ForReservingParkingSpots port, but then we would again have had the application concern depend on the presentation concern, which we want to avoid for several reasons discussed in earlier articles.

Alternatively, we could think about simply passing the three parameters startTime, endTime, and reservingMember as primitive types into the port again and moving the creation of ReservationDetails into the port-implementing service. Again, this leads to the Data Clump code smell described in an earlier article.

Conclusively, we need to honour the dependency rules and at the same time avoid excessive translation between data structures containing exactly the same fields.

In this example, we can mitigate the exception-handling issues by introducing an additional creation method on the ReservationDetails class that only takes primitive data types and returns the final ReservationDetails object.

This hides away the details of how it is created and reduces the additional potential exception handling cases to one line:

The video shows the refactoring:

Increasing Expressiveness of the Domain Model

An additional refactoring that may seem an overkill initially is to wrap the Reservation class’s constructor into a more domain-specific creation method.

In the real world, we could be talking about “scheduling a reservation”. This is information that needs to be inquired from the domain experts and is part of the ubiquitous language of that specific bounded context. A good name for that creation method could be schedule:

You can find the refactored codebase here.

Conclusion

In this article, I have demonstrated how feature envy can show us where logic may be displaced, and how we can build up a richer domain model by wrapping parts of that logic into own methods and moving them into these classes.

Furthermore, I showed how domain-specific creation methods help to hide away the complexity of how domain model classes are internally structured and created, further improving maintainability and providing a place to put validation logic.

I have also illustrated how each decision comes with trade-offs and need to be weighed against each other. Being proficient in the refactoring tools the IDE provides is therefore inevitable or else, the codebase may remain in suboptimal conditions.

The more we separate logic into smaller pieces and move them closer to the data they use, the clearer the entire domain becomes. This can also lead to breakthroughs in understanding, something not possible if we keep the code in a procedural or technically convoluted state.

Now that the domain model already contains some logic, I will explore how to move from Hexagonal to Clean Architecture. Subscribe if you don’t want to miss it:

Subscribe now

Resources

This article is part of a series moving towards a business-centric architectural design. See the following post to get started.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

To effectively learn how to identify code smells and refactor them, check out our workshop on Clean Code.

However, these data structures initially simply wrap some co-dependent data and do not much else. If we want to improve the expressiveness of our software, we need to find logic that belongs to these data structures and move it closer to them.

A couple of questions regarding data structures need to be answered before we can start moving logic into classes, which I will discuss in the following:

• Which data structures are pure data transfer objects (and thus, devoid of logic)?

• Which data structures can contain logic?

• Which data structures can be used in port interfaces?

Let’s focus on the highlighted classes in the diagram below:

In the presentation concern, there are two classes ParkingReservationRequest and - Response.

Inside the hexagon, there are ReservationDetails, ReservationId, ReservationPeriod, Reservation, ParkingSpot, and ReservingMember.

In the data-access concern, there are ParkingSpotDBEntity and ParkingReservationDBEntity.

Which of these are pure DTOs, can contain logic, and can be used in port interfaces?

Pure Data Transfer Objects

Anything that represents pure data should not contain any logic at all.

Presentation-Concern Data Structures

ParkingReservationRequest and -Response are simply class representations of JSON data structures. Thus, these two classes should only contain getters, setters, and constructors, along with utility functions like hash code or equals and toString. No mapping or business logic should be part of these classes.

Data-Access-Concern Data Structures

The same logic applies to the data structures on the data-access side. Both ParkingReservationDBEntity and ParkingSpotDBEntity simply represent a database table row. They are not business entities and should not contain any business logic either, as this would entangle the two concerns.

Data with Logic - the Domain Model

What we often refer to as the domain model in Domain-Driven Design are actually the data structures used inside the core of the hexagon to achieve some business goal.

These data structures are magnets for business logic and should therefore be used exactly for that - building up a rich domain model with functionality on the classes that make sense in the specific domain they’re used.

In Domain-Driven Design, there are three domain model types:

1. Value Objects / Values

2. Entities

3. Aggregates

Value objects, or simply Values, are context-specific objects without an identity, like for example an ID, FirstName, or Dollar. If two objects have the same values, they are treated like they were the same. They contain business logic for validation, such that they are never in an invalid state, or formatting like a PhoneNumber that can be queried for a local or international format.

Entities, on the other hand, are objects that have an identity. Two entities with the same values are only the same if their identifier, for example an ID value object, are the same. Entities contain value objects or other entities.

Entities should also use value objects as internal fields. Primitive types should only be used when domain constraints aren’t required. When in doubt, it's better to introduce a value object and later discard it than to miss an important domain constraint.

Aggregates are entities that cluster other entities and value objects so that each aggregate can be treated as a whole. Aggregates provide a transactional boundary to avoid inconsistent states. Any change to any of the internal entities can only be done through the aggregate’s methods and the internal entities should never be exposed and manipulated outside of their aggregate.

In the context, the domain model could look as follows:

ReservationDetails, -Id, -Period, and ReservingMember are value objects.

ParkingSpot would be an entity or an aggregate, but because it is currently just an ID, we could rename it to ParkingSpotId and consider it a value object as well.

The only aggregate we can see here is Reservation, but it currently lacks a dedicated ID every aggregate should be assigned when it’s created. Currently, ReservationId is only created when the Reservation aggregate is stored. Such an ID is tied to persistence concerns rather than the domain model. In a future article, we will replace it with a domain-specific, independent ID. If you don’t want to miss the article where I will do that, simply subscribe here:

Subscribe now

Of course, once we start refactoring the logic, we may notice that some definitions change and a value becomes an entity or the other way round. The current preliminary domain model could look as follows:

Data Structures in Port Interfaces

Even though we could imagine having special DTOs to transfer data between the outside world and the core, which do not expose the internal domain model, in practice, too many translation steps can become cumbersome to maintain and even start to slow down the application significantly.

Translation should be minimal such that the core is isolated from the surrounding world, but exposing certain internal structures of the domain model in the port interface does not hurt this isolation as long as we keep some rules in mind.

Let’s see which domain model classes are unproblematic to expose in port interfaces and which should be avoided under some conditions.

Inbound Port Interfaces

The transactional-boundary property of aggregates has profound consequences to what data structures can be used in inbound port interfaces:

Never expose Aggregates in inbound ports!

If we expose aggregates in inbound ports, they are outside the transactional boundaries of that port interface. Thus, changing their state outside may have unforeseeable effects, leading to strange and hard to find defects and data inconsistencies.

On the other hand, value objects pose no problem as they are simply enhanced data structures that are always in a valid state.

This has advantages because no invalid data structure can be passed into or out of the hexagon. Conclusively, we can use Value Objects in inbound port interfaces instead of unvalidated primitive types.

Outbound Port Interfaces

Outbound port interfaces behave differently than inbound ports. They are used always within the transactional boundaries of the hexagon. Aggregates are “data storage units”. Even though they are not part of the data-access concern, they should only be used in CRUD repository interfaces that are used to store and retrieve aggregates.

It could be tempting to use aggregates for other purposes, e.g. if we want to send a message that requires some or all of the aggregate’s data. However, aggregates are only safe for repository ports but should not be used in outbound messaging to prevent unintended side effects when consumed by unknown adapters. Instead, we should create a dedicated value object for such cases.

Such an uni-directional messaging port could be seen similarly to the return value of the inbound port. We don’t want to expose the internal domain model to anybody else than the dedicated repository adapters and the application-specific service class to avoid unintentional, uncontrollable changes in our data.

Value objects, on the other hand, can and should be used in all ports. Also a dedicated message object can contain the same value objects as the aggregate.

On the other hand, never expose non-aggregate entities. Neither in inbound- nor in outbound ports. They are protected by the aggregate they belong to and should only be changed using aggregate methods to ensure data integrity.

Exposing the Domain Model?

Some may argue that exposing the domain model to the outside world harms encapsulation. This is absolutely true. To circumvent that, we can still create dedicated, application-concern-specific DTOs and use them in our inbound and outbound port interfaces if that makes sense. Or simply use primitive types again.

We always need to weigh the additional translation / mapping overhead against a more isolated core. As soon as we expose the core domain model in our ports, we give away some of the freedom of changing it independently from the outside world.

If the core is only used by our team, we may choose such a more relaxed approach. On the other hand, if other teams want to integrate our core as a library, we may hide away the entire internal model and instead pass a simple data structure with primitive types and validate them within. It depends on your context which way you choose.

Conclusion

I have now illustrated which data structures can contain logic and which not. Furthermore, I showed which of them can be used in which port type.

If we want to employ a Domain-Driven Design domain model in our core, we should only expose value objects in the inbound port interfaces.

On the other hand, outbound CRUD repository ports called from within the hexagon can contain both values and aggregates as the transactional boundary is defined around the inbound port interface, shielding the aggregate from dangerous operations that could lead to data inconsistencies. However, aggregates should not be used in non-repository ports to avoid unintentional aggregate manipulation in these adapters.

Entities should neither be used in inbound- nor outbound ports as they need to be part of an aggregate and only be manipulated using methods defined on that aggregate.

Now that we know which entities can be used to move logic towards, in the next article I will show how to identify it in code and move it towards the various values and aggregates to build up a rich domain model.

Resources

This article is part of a series moving towards a business-centric architectural design. See the following post to get started.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

The port interfaces, as shown above using bright blue stickies, look as follows:

Primitive Types in Port Interfaces

The port interfaces, apart from the ParkingSpot class, currently are intentionally left primitive to emphasise the fact that hexagonal architecture does not prescribe any format, just that the outside world depends on the inside application and not the other way round.

I refer to primitive types not only for the classic low-level types like int, long, double, char, etc., but also to those types that are not associated with any of the different concerns. They could be used in any concern without creating a dependency between them.

This means that I also consider string- or collection types like lists, sets, or maps, or date-related types to be primitive types. They can be used in any generic context and do not convey any additional meaning beyond.

However, from a software design perspective, primitive types can cause issues.

Data passed back and fourth through adapters typically belongs together to some extent. Thus, they form a code smell called Data Clump, a special case of Primitive Obsession. Such primitive types lack validation and can therefore easily be passed in an invalid state, which makes an unchecked usage of them problematic.

Because of Data Clumps, the port signature is also longer than it should be, which is described by the Long Parameter List code smell. Having many primitive parameters of the same type can easily lead to a mix up, hard to read code, and code that has to be adapted in many places if the parameter list changes.

The immediate solution to these problems is to create a stronger type with a higher-level meaning. So let’s do exactly that. I try to use concern-specific names - this means that the names of types used within the hexagon, which contains only business concerns, will also get names that have a meaning in the real-world domain for which the system is built, moving the system towards Domain-Driven Design.

Introducing Stronger Types into Port Interfaces

I use IntelliJ to Introduce Parameter Objects. This refactoring automatically replaces the selected parameters with an object containing the parameters as fields.

Stronger Types in Inbound Ports

I start with the inbound port ForReservingParkingSpots. Initially, I simply summarise the 3 parameters startTime, endTime, and reservingMember into a wrapper class called ReservationDetails that I place into the application concern.

The presentation concern (the controller adapter) needs to translate the data to this input object to be able to communicate with the application. Importantly, ReservationDetails itself is a POJO free of any data-access- or presentation-concern structures like JSON or @Entity annotations, as this would violate the dependency rule. Only generic language extensions like Lombok (constructors, getters, setters) should be used for these classes.

Stronger Types in Outbound Ports

I can do the same with outbound port interfaces. For example, I can reuse the ReservationDetails object in the hasActivateReservation method like below:

And ForStoringReservations gets a Reservation class as its parameter:

Furthermore, I can also reuse the ReservationDetails class in Reservation’s constructor:

Additional Stronger Types

ReservationDetails can be further separated. For example, startTime and endTime always go together and there is no possibility to have a startTime without and endTime and vice versa. Thus, I add an additional class called ReservationPeriod that summarises the two.

Furthermore, the reservingMember string does not have any validation yet. By creating a new class ReservingMember, I can introduce a place that potentially covers that validation later and further improves expressiveness of that port.

Return Values

On the return-value side, we see that a Long value is returned in both ForStoringReservations and ForReservingParkingSpots. This is suboptimal because we can only guess its meaning from the interface signature. Having a stronger type ReservationId immediately reveals its intent.

Translating Data Structures Between Concerns

Of course, we also need to adapt the translation between the models in the adapters and service. This is the strong part of Ports and Adapters - we can build the internal model of the hexagon without having to directly consider the outside world. The adapters handle such changes and act as Anti-Corruption Layer, allowing the internal model to evolve on its own.

The current solution can be found on the branch stronger-types.

Conclusion

In this article, I have laid out why primitive types can hurt expressiveness, and how stronger types can make port interfaces much easier to read and comprehend without having to dive in deep into the actual implementation.

The introduced data structures are all part of the business concern and can therefore be used not only by that, but also by the adapters to translate between the internal and the external model.

However, there are some restrictions and considerations when it comes to exposing data structures from the business concern outside of the hexagon which I will explore in the next article.

Additionally, the types currently are simple data holders without any additional logic associated with them. In the next article, I will also discuss which data structures should remain such simple DTOs, and which on the other hand could be used to build up a rich domain model. Subscribe if you don’t want to miss it:

Subscribe now

Resources

This article is part of a series moving towards a business-centric architectural design. See the following post to get started.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

The “driven” side, which is called that way because it is driven by the application service as indicated by the vertical line inside the hexagon, now obeys the rules of Ports and Adapters. But are there still adaptations needed to be able to talk of a real “hexagonal architecture”?

Interface Segregation Port on the Presentation Side

Indeed, if we look at the “driving” side, meaning the left side of the diagonal in the diagram from where the application is called, we can see that there is still a direct dependency from the controller to the application service.

This is not perfect as the application service may expose various public use-case methods that the controller doesn’t need to know about.

However, especially during transition phases from a technical service with multiple use-case methods to a cleaner, business-centric structure, it is advisable to first logically split the service into individual use-case methods and then step-by-step split it up physically into smaller services.

This can be achieved by employing interface segregation and using these interfaces in place of the actual service within the controller, reminiscent of the strangler-fig pattern. The controller won’t need to know that behind the scenes, it is actually using a large service. This makes the controller also easier to test, as only one method needs to be stubbed and not an entire service with many methods.

The resulting structure looks as follows:

Importantly, this interface or port only contains either primitive- or application-specific data structures and no data structures or annotations of the presentation concern (i.e. DTO representations of JSON, XML, etc.) anymore.

This driving port on the left side of the diagonal in the diagram is used by the controller and implemented by the application service, which is different from the ports on the right side of the diagonal, which are used by the application service, and implemented by the data-access adapters.

Thus, the controller effectively becomes the adapter between presentation and application concerns as it adapts the JSON DTO to a representation prescribed by the application service.

Naming Ports

In the diagram, we should treat 1 edge of the hexagon as 1 port, and each port is for doing something. So we should always ask ourselves: what is this port for?

I prefer to name port interfaces according to the action that they perform. Thus, a possible name could be “ForReservingParkingSpots”. Alternatively, “ReserveParkingSpot” would also serve the purpose of illustrating such an action.

I would avoid naming these segregated interfaces with only 1 method signature with a noun, because only their implementations typically represent objects that are nouns, as they often implement multiple different port interfaces or represent a real-world concept like ReserveParkingSpotUseCase.

Interface Segregation on the Repository Side?

If we move our attention again to the driven side of the hexagon, we can see that this naming rule is actually not applied yet. We use “repository” in the name for both ports.

From a ports and adapters perspective, we can also split these two repository interfaces into single ports that only contain one public method signature each.

This approach can have several advantages, e.g.

1. Each port can have another implementation, e.g. if queries and commands use different endpoints.

2. Multiple ports can be implemented by one repository, but the application service / hexagon only needs to know about the methods it actually requires.

3. Using stubs and fakes in unit tests is simplified, making it easier to apply Outside-In Test-Driven Development where we focus on the interfaces the application interacts with instead of their implementation.

In practice, it is usually rather inconvenient to separate CRUD repository interfaces into several single-method ports as the user of these interfaces often expects to find these methods in the same place according to the repository pattern.

This is why I would only split them up if there is a reason for it. On the other hand, if we use a modern IDE, extracting or inlining an interface is trivial, so we can also play around with different designs and decide on a case-by-case basis.

To name these ports we can ask again “what is this port for?”. Reasonable names could be “ForCheckingActiveReservations”, “ForStoringReservations”, or “ForFindingParkingSpots”, or simply their action names “CheckActiveReservations”, “StoreReservation”, “FindParkingSpots”.

Thinking about ports that way without considering how they are implemented eventually lets us focus much more on what needs to be accomplished by the application from a business perspective rather than how we store the data, a key consideration also when we want to add additional concepts on top of hexagonal architecture, like Clean Architecture or Domain-Driven Design Tactical Patterns.

Ports Location

As a reminder, both inbound and outbound ports are defined in the application / service concern. However, they are used (inbound ports) or implemented (outbound ports) by the respective presentation- or data-access concern class, which are located outside the application concern.

Conclusion

Interface segregation, one of the 5 SOLID principles, can help us focus an application on the actions it needs to perform, meaning its behaviours, rather than the technologies and patterns used to perform these actions.

It achieves this by ensuring ports only contain one (or a few) method signature(s) with a specific, actionable name each like “ForStoringReservations” or “StoreReservation” instead of generic noun-based names that are magnets for all kind of unrelated method calls.

However, keep in mind that having a large number of one-method interfaces can be cumbersome to work with as well, so combining related interfaces into one (because they change for only one reason and together), e.g. for the sake of creating CRUD repository interfaces, can greatly enhance usability. Balance is key. There is no one size fits all, which is why you should be proficient in your IDE’s refactoring tools.

In the next article, I will have a look at how we can improve expressiveness by introducing concepts from Domain-Driven Design, so if you haven’t already, subscribe if you don’t want to miss it:

Subscribe now

Resources

This article is part of a series moving towards a business-centric architectural design. See the following post to get started.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

By doing so, I could effectively get rid of the framework-dependent data-access types and repositories, effectively separating the two concerns.

Current Dependencies

The current application service still depends on the new data-access adapter, as can be seen below:

I want to visualise this with the following diagram. The data-access adapters effectively separate business concerns from data-access concerns by mapping between the two. Most of the passed data is currently primitive. ParkingSpot is a data structure defined within the application concern and is used by the data-access adapters.

This is actually the first step to invert the dependencies: for a truly business-centric architectural design, the data-access concern needs to depend on the business concern, not the other way round.

By employing primitive- or application-specific types in the repository adapter’s method signatures, I already have achieved half of the transformation.

However, the application service ParkingSpotReservationService still directly calls the data-access repository adapters.

Data-Access Adapters inside the Business Concern?

To achieve a pure business-centric architecture, both ParkingSpot- and ParkingReservationRepositoryAdapters should not directly be called by the application service anymore.

This is where Hexagonal Architecture’s Ports come in handy: we can define interfaces inside the service package / business concern, which are then implemented by these data-access adapters.

These interfaces are going to be the ports through which the business concern is interfacing and interacting with the data-access concern.

So let’s do exactly that by pulling up the method signatures of the two adapters into two interfaces ParkingSpotRepository and ParkingReservationRepository, which are then implemented by the respective adapters:

I use IntelliJ’s built-in features to extract a new interface and place it in the service package (for now. I will show possible package structures in a later article).

You can find the solution on the following branch: introducing-data-access-interfaces.

Dependencies after Ports Creation

After creating adapters that map between data-access- and business concern, introducing port interfaces as part of the business concern that only use either primitive- or business-concern-specific data types, and making the data-access adapters implement those interfaces, there are finally no direct calls/dependencies from the business- to the data-access concern anymore.

This can also be seen in the imports declaration at the top of the service:

The data-access concern is isolated as well, only depending on the port interface definitions of the application-service package.

This step finalises the dependency inversion, such that the business- does not depend on the data-access concern anymore, but the other way round.

It additionally illustrates the dependency relationships between ports and adapters on the driven (right) side of the diagonal line in the hexagon, as the following diagram illustrates:

Conclusion

Inverting dependencies between business- and data-access concerns is one of the most important steps to move towards a business-centric structure like Hexagonal Architecture.

The important part to remember is that the interfaces (or ports), together with the data structures they employ in their signatures, are defined within the application concern and implemented by the data-access concern. There can’t be any dependency from application- to data-access concerns!

In the next article, I will show what may still be missing until we can truly speak of Hexagonal Architecture, so subscribe if you haven’t already not to miss it:

Subscribe now

Resources

This article is part of a series moving towards a business-centric architectural design. See the following post to get started.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

I will continue with the same codebase on the branch separating-presentation-concerns. You can also find all the step-by-step modifications in the video below. If you don’t want to miss future articles on this topic, simply subscribe here:

Subscribe now

Choosing Appropriate Names for DB Entities

Let’s start by investigating the two entities present in the model package, ParkingReservation and ParkingSpot. Both are actually SQL table rows represented as Java objects:

They are part of the data-access framework we use and should not be part of the application service. Neither should they contain any business rules.

Instead, they should be seen as simple anaemic data containers with respective getters and setters that represent the cells in a SQL row.

Thus, to better mark these entities as the SQL rows they actually represent, I choose to rename them to:

• ParkingReservationDBEntity

• ParkingSpotDBEntity.

This will make it easier to distinguish them from application-specific data structures we’ll introduce later. Additionally, I rename the corresponding repositories accordingly to:

• ParkingReservationDBEntityRepository

• ParkingSpotDBEntityRepository.

Mapping between Business- and Data-Access Concerns

An important idea to achieve concern separation and thus independence from the data-access frameworks or technologies is to keep as much of their annotations and magic out of the business concern as possible.

This means that we need to map between data-access- and business concern data structures that we exchange between these two layers, and that the data-access-to-business-concern mapping function called by the business concern cannot expose any data-access data structure to that business concern.

So let’s get started :)

Adapting Parking Reservations

As a first step, I create a ParkingReservationRepositoryAdapter in a new data_access package and add the ParkingReservationDBEntityRepository as a field. This is going to be the class that handles mapping between data-access and business concerns.

As a second step, I investigate the application service to see which calls I need to map data to and from.

The first access to ParkingReservationDBEntityRepository is actually the “hasActiveReservation” call. The signature of this method does not have any data-access specific entities, so in theory, it corresponds to the rule that there should be no data-access class in the business service.

However, I want to eventually get rid of any data-access repository, so I will for now simply let the ParkingReservationRepositoryAdapter delegate this method call to the ParkingReservationDBEntityRepository:

Adapting Parking Spots

As a next step, I want to create a similar delegation for the ParkingSpotDBEntityRepository’s findAnyAvailableSpot method. This time, I need to map the DBEntity to a corresponding class of the application service.

Let’s implement it as ParkingSpot and add it to the service package. This class will currently only contain the Long id that it gets from the ParkingSpotDBEntity.

I create a method inside the application service that returns an Optional<ParkingSpot> and map the found ParkingSpotDBEntity’s id to it if it is not null, effectively getting rid of the implicit null check for availability in the application service. I can then move the method to the ParkingSpotRepositoryAdapter and use it in the application service:

Storing a new Parking Reservation

As a third step to remove the framework-dependent data-access repositories, I want to hide to steps to create a new Parking Reservation, i.e. that also a ParkingSpotDBEntity’s isAvailable field needs to be set to false.

To do so, I wrap the entire creation & storage of the reservation, together with altering the spot’s availability, in an own method storeReservation:

There is one additional step compared to the previous entangled solution to effectively separate the two concerns: I need to find the ParkingSpotDBEntity once again by id and set its availability to false.

An alternative solution could have wrapped also the search for an available spot, but in my opinion, we would move too much business-relevant logic into the repository adapter.

I want to keep my repository adapter as dumb as possible for now, and fetching the same parking spot twice seems like a reasonable trade-off. However, this initial solution may change in a later article.

If we look at the signature, we see that there are only primitives and the ParkingSpot class present. Even though not optimal, this signature is entirely free of data-access-specific classes, so the separation of business- and data-access concerns is almost complete.

I can finally move the method into the ParkingReservationRepositoryAdapter:

And use it in the application service:

This solution now contains no data-access types like ParkingSpotDBEntity or ParkingReservationDBEntity anymore but only business-concern-specific ParkingSpot and primitive data types, effectively separating business- from data-access concern. You can find this solution on the separating-data-access-concerns branch.

Conclusion

In this article, I have demonstrated how we can separate the business- and data-access concerns by introducing adapters that map between the two.

There is still some work left: even though the methods of the adapter classes already only use application-specific data structures or primitive types, the application service still depends on these adapters, which means that the business concern knows about the data-access concern.

In a next step, therefore, I want to demonstrate how to finally get rid of any data-access dependency and implement a truly business-centric architectural design pattern reminiscent of Hexagonal Architecture. Subscribe if you don’t want to miss it:

Subscribe now

Resources

This article is part of a series moving towards a business-centric architectural design. See the following post to get started.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

Presentation Concern And Application Services

The presentation concern has three major tasks:

1. Mapping incoming presentation data (e.g. a JSON) to an application-service-specific input format.

2. Invoking the application service’s use case method.

3. Mapping any potential output from the application service to a presentation output format (e.g. HTTP / JSON).

It’s not necessarily the presentation concern’s task to validate input data. Instead, the service method needs to ensure that only valid data can be used to invoke it and handle cases of invalid data. This could be throwing exceptions or returning an error result.

Let’s get back to the codebase you can find here and move all presentation concerns out of the service and into the controller!

Separating Presentation Concerns from Application Service

There are several places in reserveParkingSpot where presentation data structures are directly accessed and presentation logic is used to create and return presentation-specific results, see the orange parts below.

However, converting input and results to and from the application service should only happen in the presentation concern, meaning in the corresponding ParkingSpotReservationController, which currently only delegates inputs to the service method without any mapping and directly returns whatever the service produces:

Let’s get started with the separation! You can also watch the following video alongside to see the applied refactoring techniques in action.

Isolate Presentation DTOs

Currently, there are multiple accesses to the request’s startTime, endTime, and reservedBy fields. To access them independently from the presentation’s ParkingReservationRequest DTO, we can first extract the 3 fields into separate local variables and use them instead of the request’s getters:

We can apply the same to the reservation’s ID at the end of the method when we map back to a ParkingReservationResponse DTO:

We already achieved some local separation by only using primitive data types like LocalDateTime or String that are neither presentation-, nor data-access or business-concern-specific.

Replace Return Types with Exceptions

As a next step, we need to separate HTTP return values from the business rules that cause them.

To do so, I start to throw business-specific exceptions in the service where the responses were returned previously, and then map them to the HTTP ResponseEntity in the catch clause.

Let’s start by adding the try-catch around the non-presentation part of the reserveParkingSpot use case method:

We need to also move the Long reservationId outside of the try-catch as we need to return it from the service and then use it in the ParkingReservationResponse.

Let’s turn the first error case for “Reservation must be at least 30 minutes long.” into an exception ReservationShorterThan30MinutesException and handle the case in the catch part.

We should do this for all the exceptional cases. We can additionally introduce the following exceptions in the service package:

• EndTimeMustBeAfterStartTimeException

• ReservationOutsideOperatingHoursException

• ActiveReservationExistsException

• NoAvailableSpotsException

And handle them accordingly in the catch clause:

Physically separating business rules further from presentation logic.

Move Presentation Concerns to Controller

Now we can extract the part within the try {} block into an own method, for example reserveParkingSpot2:

We can turn this method public and inline the outer reserveParkingSpot method into the ParkingSpotReservationController, and then rename it to reserveParkingSpot.

The final service method is free of any presentation concern:

The controller, on the other hand, now does exactly what I initially outlined. It:

1. Maps incoming presentation data to an application-service-specific input format.

2. Invokes the application service’s use case method.

3. Maps any potential output from the application service to a presentation output format (e.g. HTTP / JSON).

There are still other transformations possible, but for presentation concern separation, this is about it! You can find this solution on the following branch: separating-presentation-concerns.

Conclusion

In this post, I demonstrated how to effectively remove presentation concerns from application service by introducing service-specific exceptions and handling them within a try-catch block.

In the next post, I will also encapsulate data access concerns and remove them from the service method, so stay tuned if you don’t want to miss it by subscribing to our blog:

Subscribe now

Resources

If you want to effectively discern concerns, see the following post.

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Hexagonal and Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

Any framework or language has a specific convention of how to structure code. If you work with Java and Spring Boot, the following package structure may look familiar:

There are many applications that follow exactly this structure and it can feel impossible to move towards a more business-centric architectural design like Hexagonal Architecture by Alistair Cockburn without the right approach.

This is why I will provide a step-by-step guide to achieve exactly that.

Because the entire topic is pretty large, I split it into a couple of articles that I will publish about once a week. You can follow along using my repository. Subscribe if you don’t want to miss it!

Subscribe now

Before we can move towards Hexagonal Architecture, we need to be able to effectively identify different concerns. This is what I will look at in this article.

Typical Concerns in any Application

There are 3 to 4 concerns that any application has, which are:

1. Data Access: how we retrieve and store data. These are typically in-memory, file system, databases, or surrounding system calls.

2. Presentation: how data is presented to a user. This can involve JSON data structures, HTML pages, XML, PDF, or any other data and presentation logic that is used to deliver data from the user to the system and then back again by the system to the user.

3. Application/Business: the actual core of any software. Also referred to as “business rules”, this is how a company makes or saves money. While data access and presentation concerns may change frequently due to framework updates or exchange of technologies, the application concern should actually only change when business processes change. It’s best kept free of framework-specific code. This is sometimes impractical and there are exceptions to this rule, but the mindset when implementing this concern is to keep external dependencies to a minimum.

I said 3 to 4 concerns, so here’s the 4th concern which is not necessarily required but helps with emphasising the business view:

4. Domain: we can split off the domain concern from the application concern if we are interested in creating a rich domain model as described by Domain-Driven Design. Although not essential, it is highly advisable to create a richer domain model to capture business rules and decisions, especially if we are dealing in complex business domains.

If we split the domain concern off from the application concern, then the application concern is tasked with checking global validation, retrieving and storing domain entities, and invoking a domain entity’s business rules.

In the following, I will mainly focus on the 3 concerns presentation, data access, and application. Domain will become relevant in later articles when I will show how to move towards a more business-centric structure.

A Naive Approach to Identifying Concerns

After laying out the basic building blocks of an application, let’s investigate the Spring Boot app again. Where are the 3 concerns located? A naive interpretation could be the following:

The controller package is concerned with presentation logic. The repository package is concerned with data access. The service package contains application-specific service classes. And then we have the DTO package for JSON representations of the presentation concern, and a model package for the domain model.

Makes sense, right? Unfortunately no.

In reality, Spring Boot mixes up several different concepts from MVC and DDD and probably others as well. For example, let’s see what the @Service annotation defines:

public @interface Service

Indicates that an annotated class is a "Service", originally defined by Domain-Driven Design (Evans, 2003) as "an operation offered as an interface that stands alone in the model, with no encapsulated state."

May also indicate that a class is a "Business Service Facade" (in the Core J2EE patterns sense), or something similar. This annotation is a general-purpose stereotype and individual teams may narrow their semantics and use as appropriate.

We see that it can basically be anything a developer team may define as a “service”. This is not helpful but on the contrary, a great way to create chaos before even getting started, as everyone has another definition of what a “service” entails.

Conclusively, we cannot rely on framework-defined stereotypes to effectively identify concerns, a point I want to drive home even more with the following analysis.

Identifying Real Concerns in Code

Let’s take a look at the following code snippet you can find here. Can you easily spot what concern this class belongs to?

The class name suggests that it is an application-specific service. This means it should concern itself only with coordinating and applying business rules.

However, let’s look at the service method’s signature:

The return type indicates a REST HTTP response, which is part of the presentation concern. The same is true for the ParkingReservationRequest, which is a Java DTO representation for a user-provided data structure, most likely JSON. It is directly passed from the controller to the service, as can be seen here:

Application-specific services should not use data structures from the presentation concern.

If we look a bit deeper into the service’s reserveParkingSpot method, we find three guard clauses that need to be passed before the reservation request is processed any further:

This is actually a mix of business rules and presentation logic. The business rules are the checks on both start- and end time, which are taken directly from the presentation concern’s request DTO, and then the code returns a presentation-specific ResponseEntity object with corresponding HTTP status codes. There is an awful lot of presentation logic going on in this business-application-specific service.

In the next couple of lines, presentation concerns and business rules are additionally entangled in data access concerns:

ParkingSpot is a database entity, basically an object representation of a database table row in the case of SQL, and not a real business object, even though it is typically stored in the model package.

Checking if the spot returned from the repository is null is an indirect and highly ambiguous way to represent the business rule that a spot needs to be free to be reservable.

In the case of making a parking spot reservation, we actually mix both business rules and data access concerns so smoothly together that we cannot simply distinguish the two visually, which is why I use a blue-green gradient to do so.

Reserving a parking spot means creating a ParkingReservation database entity entry and setting the ParkingSpot’s availability to false.

However, this actually only represents how we store the information in the database and obscures the business rule “reserve parking spot”. We rely solely on the interpretation- and mental-mapping abilities of a programmer to understand its semantics. This may be acceptable in a simple example like the one presented here, but can quickly turn almost impossible to maintain in a more complex environment.

If we look closer into the query of the repository methods, we find additional business rules encoded:

Apparently, we get the next randomly available parking spot. We could decide to implement that differently, e.g. if we want to provide different categories of parking spots to customers. It’s a business decision to randomly select a free spot, so we mix business- with data access concerns once again.

In a last step, we map the data from the presentation request and the database entity’s ID to a presentation response DTO. None of this should happen directly within an application service, which should only handle business-application-specific concerns.

Conclusion

In this small example, I have demonstrated how framework-specific stereotypes and attributes like @Service are no guarantee at all to identify different concerns effectively.

On the contrary, because frameworks are typically expected to accommodate as many developer and team interpretations as possible, it’s easy to unintentionally mix different concerns without even realising it.

In the case of complex business logic, this mixing of concerns can heavily impact our ability to change software quickly and cheaply over time because the codebase deteriorates into a Big Ball of Mud.

Being able to quickly discern different concerns within our codebase is a vital skill needed to move towards a more business-centric application structure. In the upcoming articles, I will step-by-step illustrate how to transform the presented codebase into a Hexagonal Architecture / Ports and Adapters.

If you don’t want to miss it, just subscribe here:

Subscribe now

Resources

This series of articles is an addition to the From Layered to Hexagonal Architecture in 2 steps article.

We touch on the same topics in our O’Reilly course “DDD, EventStorming, and Clean Architecture”. Check it out to learn how to use Classic TDD to implement DDD Aggregates in Clean Architecture.

If you want to learn more about effectively separating concerns, you could also have a look at our on-premise, remote or hybrid workshop Modern Software Architecture Design Patterns.

Parallel Change is one of the most powerful refactoring techniques, but it has also another use: seamlessly moving from a single element to a collection of elements. This corresponds to the transformation step scalar → array in the Transformation Priority Premise (TPP).

Often when I moved from 1 to many using TDD, I found myself mindlessly ripping out old code and adding new code. Obviously, I often ended up in a state where my code did not compile anymore for quite some time!

All of a sudden it clicked - it’s the same problem that I had while refactoring and exchanging an existing abstraction with a another one. So Parallel Change should help me similarly as it does during refactoring, only this time I use it to move from a failing to a passing test.

The Example: Popping 2 Elements from a Stack

I take the example of a stack (which I borrow from Clean Craftsmanship by Uncle Bob), which shows exactly the case of moving from 1 element to a collection of elements. The relevant failing test (that you can also find here) reads as follows:

@Test
void pops_elements_in_the_reverse_order_of_how_they_were_pushed() {
    var stack = new Stack();

    stack.push(99);
    stack.push(88);

    assertEquals(88, stack.pop());
    assertEquals(99, stack.pop());
} 

This test currently fails because of the following code for a stack which only supports storing 1 element, so once 88 is pushed into the stack, 99 gets overwritten:

public class Stack {
    private int size;
    private int element; // only one element

    public boolean isEmpty() {
        return size == 0;
    }

    public void push(int element) {
        this.element = element; // overrides element
        size++;
    }

    public int pop() {
        if (size == 0) {
            throw new EmptyStackPoppedException();
        }
        size--;
        return element;
    }

    public int size() {
        return size;
    }
}

Parallel Change Revisited

Let’s see how we can leverage Parallel Change to move this test from red to green by replacing the single element with a List. Here’s a brief summary of Parallel Change:

1. Add the new List close to the element to replace.

2. For every time a value is assigned to element, add the same value to the List.

3. Switch all reads from element to an equivalent read operation from the List.

4. Remove all places where the element is assigned a value.

5. Remove the element member variable.

Applying Parallel Change to Get to Green

In step 1, we add the List right below the element and run our tests. Only the test from above should still fail.

public class Stack {
    private int size;
    private int element; 
    private List<Integer> elements = new ArrayList<>(); // new
    
// ...

In step 2, we add a value to the List wherever that value is assigned to element. Here, it’s only once in the push method. Still the same test should fail because only the state in element and the List are now the same, but we don’t access the list yet.

public void push(int element) {
    this.element = element;
    this.elements.add(element); // add this here
    size++;
}

In the 3rd step, we’ll make the test green by replacing all read accesses to element with a read access to elements. We leverage the List’s removeLast in the pop method. Finally, the test is green.

public int pop() {
    if (size == 0) {
        throw new EmptyStackPoppedException();
    }
    size--;
    // previous: return element;
    return elements.removeLast(); // new line
}

The step before would have shown us if we actually had the same state in both element and the List. We can now step-by-step remove occurrences where element is assigned a value to (while running our test suite after each step):

public void push(int element) {
    // remove this line: this.element = element;
    this.elements.add(element);
    size++;
}

And finally, we are ready to remove element entirely from the stack, resulting in the following solution:

public class Stack {
    private int size;
    // removed: private int element;
    private List<Integer> elements = new ArrayList<>();

    public boolean isEmpty() {
        return size == 0;
    }

    public void push(int element) {
        this.elements.add(element);
        size++;
    }

    public int pop() {
        if (size == 0) {
            throw new EmptyStackPoppedException();
        }
        size--;
        return elements.removeLast();
    }

    public int size() {
        return size;
    }
}

This finalises the Parallel Change for the 1 to Many Transformation from element to the List, but we’re not yet done. We used Parallel Change to move from red to green, and now we enter the refactoring stage! And there is something to refactor: we still have the member variable size that can now be removed, also using Parallel Change, so let’s apply it once again.

Parallel Change for Refactoring Revisited

We can skip steps 1 and 2 of the Parallel Change algorithm (achieving the same state in old and new structure) as we already solved the introduction of the new abstraction (elements) and setting the same value as size because every time an element is pushed to the list, it’s size automatically increases.

So instead, we can directly move to step 3 and replace all the read accesses to size with a read access to elements. Let’s start with Stack::isEmpty:

public boolean isEmpty() {
    // replaced: return size == 0;
    return elements.isEmpty();
}

Then we move to pop. Here we can use the improved Stack::isEmpty method, which should have been used in the first place as it was a case of D.R.Y:

public int pop() {
    if (isEmpty()) { // use the public Stack::isEmpty method here
        throw new EmptyStackPoppedException();
    }
    size--;
    return elements.removeLast();
}

And finally, let’s also adapt Stack::size:

public int size() {
    // replaced: return size;
    return elements.size();
}

Now that we have switched all the read accesses to the List, we can move to step 4 and remove all the places where size is assigned a value:

public void push(int element) {
    this.elements.add(element);
    // remove: size++;
}

public int pop() {
    if (isEmpty()) {
        throw new EmptyStackPoppedException();
    }
    // remove: size--;
    return elements.removeLast();
}

And finally, in step 5, we remove the size member variable and are left with the following Stack:

public class Stack {
    // removed: private int size;
    private List<Integer> elements = new ArrayList<>();

    public boolean isEmpty() {
        return elements.isEmpty();
    }

    public void push(int element) {
        this.elements.add(element);
    }

    public int pop() {
        if (isEmpty()) {
            throw new EmptyStackPoppedException();
        }
        return elements.removeLast();
    }

    public int size() {
        return elements.size();
    }
}

… and we never broke a sweat.

Conclusion

This simple example illustrates how Parallel Change can both be used in TDD to solve the 1 to many transformation and seamlessly move from red to green, and also to replace an existing abstraction with another one in the refactoring phase.

Applied correctly, we never enter a state of non-compiling code and avoid Analysis Paralysis when we run into problems. I highly recommend you try out the example for yourself in the following repository (the solution can be found here). It’s a great tool to have in your TDD toolbox!

Have you applied Parallel Change in that manner before? Do you have other systematic strategies to move from 1 to many in TDD? Write them down in the comments so we can learn from one another!

Leave a comment

If you like content like that, don’t forget to subscribe to stay up to date!

Subscribe now

In our O’Reilly course we demonstrate a similar move from 1 to many using Parallel Change for extending a Clean Architecture Use Case from 1 Aggregate to a Repository of Aggregates, step-by-step using TDD. Check it out!

Want your team to learn how to develop evolvable software solutions? Visit our website www.codeartify.com and get in touch with us! We provide worldwide remote and on-site workshops for you and your team!

And lastly, if you are not yet part of our great community, check out our Tech Excellence Meetup and discuss with other likeminded people in Discord!

So your code doesn’t compile anymore (again)?

I assume we all have been in this situation once in our software engineering career: we need to replace an old piece of code with a new one. This could be something as small as replacing a List with a stronger domain type like CustomerAddresses, or replacing an old SQL connection with a new NoSql database. Maybe you even need to replace an entire system with a new one.

Whatever the scale of the task, sooner than later, we find ourselves ripping out old code and trying to integrate our new code. Often, this is when the codebase does not compile anymore. Other teams may be pushing more features into main, which we’ll have to integrate into our non-compiling code mess. Thus, the complexity of the task increases continuously with every day we cannot merge our code.

Days may go by where we try to get our code to compile and our tests green again, but at some point, we may simply give up and revert it all. The complexity is just too high. If we cost 100$ an hour and spend 2 work weeks on it, we may have just burned through 8000$ or more in the process! That’s certainly not what our employer expects to pay for us for essentially accomplishing nothing at all!

Is there a better way to replace old with new that ensures our code always compiles, our tests remain always green, we can merge to main at any time, and continue changing our code at a later stage, should the product require us to work on something more urgent like a bug?

Parallel Change to the Rescue!

The technique that shines in replacing old with new code without breaking it in the process and which scales from variables to system level is called Parallel Change.

As far as I’m aware, the technique was famously illustrated by Joshua Kerievsky (Refactoring to Patterns/Industrial Logic), see e.g. here around the 21 minutes mark. I highly recommend you have a look at that presentation as well.

The Idea behind Parallel Change

The idea behind Parallel Change has its origins in construction work. Imagine the task to refurbish or replace an old road. You cannot simply close down the entire road for a year or two. Instead, cars will still need to be able to continue driving on the old road while the new one is being build, even though there may be slow downs. The goal is to keep traffic running while at the same time refurbish the old road.

This is exactly what we want to achieve with our system: the user should not experience a complete shutdown. Some delays may be acceptable, but the system should continue running while behind the scenes it is being changed. So let’s investigate how Parallel Change ensures our code can always be merged to main.

Parallel Change Workflow

Parallel Change works as follows:

1. Create the new piece of code you want to replace an old one with (with tests!).

2. Add the new piece of software right next to the old one.

3. For every write (command) to the old software, add a write to the new one, step-by-step, and run your tests after each addition.

4. Switch every read access (query) from the old piece of software to the new one, step-by-step, and run your tests after each switch.

5. Remove all the writes to the old software, step-by-step, and run your tests after each removal.

6. Remove the old piece of software.

Step 3 ensures the state in both old and new pieces of software is the same, while in step 4, we will find out if we actually have the same state in both pieces. Until step 3, nothing should break, while in step 4, we potentially have a problem if we forgot any of the writes, so we need to have a strong test suite to validate if we have broken anything. Always run this test suite after a change!

Parallel Change allows you to commit after every step and know that the system still works! You can integrate immediately and change the system over a long period of time, sometimes years, without breaking a sweat. You could even replace entire systems that way. Traffic continues to flow even though there may be some obstacles and slowdowns on the way. Let’s now see a real code example (see also the video).

Parallel Change with a Simple Code Example

To illustrate how you can apply Parallel Change in your codebase, I have prepared the following small example that you can also find in the repository.

public class Circle {
    private int x;
    private int y;
    private int radius;

    public Circle(int x, int y, int radius) {
        this.x = x;
        this.y = y;
       this.radius = radius;
    }

    public boolean contains(int x, int y) {
        return (x - this.x) * (x - this.x) 
               + (y - this.y) * (y - this.y) 
               <= radius * radius;
    }

    public void moveTo(int x, int y) {
        this.x = x;
        this.y = y;
    }

    public void resize(int radius) {
       this.radius = radius;
    }
 
    public String format() {
       return "circle: {" +
             "\n\tcenter: (" + this.x + "," + this.y + ") " +
             "\n\tradius: " + this.radius + "\n}";
    }
}

The goal is to replace x and y with a stronger Point record. The first step is to create and add a new instance of Point right next to the coordinates as center, see below.

public record Point(int x, int y) {}

public class Circle {
    private int x;
    private int y;
    private Point center; // add center point
    // ...
}

As a next step, we find all the places where x is written to and add an equivalent write operation to the point class. Because x and y always come in pairs, this will also solve writing the corresponding y value. However, our initial focus is on x. There are two places where x is written to, one in the constructor and one in the moveTo method, see below.

public class Circle {
    private int x;
    private int y;
    private Point center;

    // ...

    public Circle(int x, int y, int radius) {
        this.x = x;
        this.y = y;
        this.center = new Point(x, y); // set center
        // ...
    }

    // ...

    public void moveTo(int x, int y) {
        this.x = x;
        this.y = y;
        this.center = new Point(x, y); // set center
    }

We run our tests after each step. Up until now, nothing should break as we only added code. The center point should now always have the same state as x (and by coincidence, also y). In the next step, we will switch every call to get the value of x to a call to center.x() and run our tests every time we switch. Three places need to be adapted, two in the contains method and 1 in the format method.

public class Circle { 

    // ...

    public boolean contains(int x, int y) {
        return (x - this.center.x()) // read center.x()
             * (x - this.center.x()) // read center.x()
             + (y - this.y) * (y - this.y) 
             <= radius * radius;
    }

    // ...
 
    public String format() {
       return "circle: {" +
             "\n\tcenter: (" + this.center.x() // read center.x()
             + "," + this.y + ") " +
             "\n\tradius: " + this.radius
             + "\n}";
    }
}

Now, x is not read from anymore, only from center.x(). We can now step by step remove writes to x, until the variable x is entirely dead code, and finally remove it. The resulting code looks as follows:

public class Circle {
    private int y;
    private Point center;
    private int radius;

    public Circle(int x, int y, int radius) {
        this.y = y;
        this.center = new Point(x, y);
        this.radius = radius;
    }

    public boolean contains(int x, int y) {
        return (x - this.center.x()) * (x - this.center.x()) 
             + (y - this.y) * (y - this.y) 
               <= radius * radius;
    }

    public void moveTo(int x, int y) {
        this.y = y;
        this.center = new Point(x, y);
    }

    public void resize(int radius) {
       this.radius = radius;
    }
 
    public String format() {
       return "circle: {" +
               "\n\tcenter: (" + this.center.x() + "," + this.y + ") " 
            +  "\n\tradius: " + this.radius
             + "\n}";
    }
}

We can now follow the same process to get rid of y. Step by step switch all reads from y to center.y() and run the tests after each step, then remove all the writes to y, and finally, remove the member variable y. Eventually, we arrive at the following code:

public class Circle {
    private Point center;
    private int radius;

    public Circle(int x, int y, int radius) {
       this.center = new Point(x, y);
       this.radius = radius;
    }

    public boolean contains(int x, int y) {
        return (x - this.center.x()) * (x - this.center.x())
             + (y - this.center.y()) * (y - this.center.y())
               <= radius * radius;
    }

    public void moveTo(int x, int y) {
        this.center = new Point(x, y);
    }

    public void resize(int radius) {
       this.radius = radius;
    }
 
    public String format() {
       return "circle: {" +
               "\n\tcenter: ("
               + this.center.x() + ","
               + this.center.y() + ") " +
             "\n\tradius: " + this.radius
             + "\n}";
    }
}

Both x and y have been completely removed, the code always compiled, the tests where always green. We could commit at every step of the way, go home, merge into main, and nothing would have broken our code.

This algorithm scales from small examples to system levels and can also be used for example for database migrations. Give it a try!

If you want another example to practice, you could try to replace the radius variable with a strong type Radius. Have a look at the repository and the solution on the branch solution_parallel_change.

How do I realise I need Parallel Change?

When I first started with Parallel Change, I didn’t realise it’s full potential until I found myself time and time again in a broken system. Whenever it felt like “I never get that software to compile again”, I realised that I forgot about Parallel Change. So, the next time you find yourself in a situation where you end up with non-compiling code and analysis paralysis, remember not to get any SADER (pun intended ;)):

1. Set up the new structure

2. Add parallel writes to the new structure

3. Divert reads from the old to the new structure

4. End writes to the old structure

5. Remove the old structure

Parallel Change will transform the way you approach complex code changes!

Have you experienced similar issues while changing code? What was your strategy to get over the issues of non-compiling code for a long time?

Leave a comment

If you like content like that, don’t forget to subscribe to stay up to date!

Subscribe now

Want to learn how to apply Parallel Change in Classic TDD to get from 1 to many? Check out our comprehensive O’Reilly course that demonstrates exactly that.

Want to learn how to write evolvable code? Visit our website www.codeartify.com and get in touch with us! We provide worldwide remote and on-site workshops for you and your team!

Without the right techniques and tools, refactoring can become a nightmare. Code that does not compile for a long time, failing tests after we finally made it compile again, and bugs after we deploy the refactored code to production.

We may end up in analysis paralysis trying to figure out where our refactoring went wrong. In the worst case, we may need to revert weeks of changes because the codebase diverged so much.

It does not have to be that way. In this article, I want to demonstrate to you how adapt your way of thinking about refactoring and how to keep your code always in a compiling state with only little chance of introducing unwanted behaviours, using only 5 automated refactoring tools to do so.

Refactor in Baby-Steps

Your mindset should be that you only refactor one small thing, run your tests, and then commit. The more complex the refactoring goal, the smaller your step should be.

The goal is to always try to stay in a state of flow. If you notice that the [refactor step - test - commit] cycle becomes boring, you may add some additional steps before running tests again and committing.

On the other hand, if you refactor too much at once and end up with code that does not compile anymore or with failing tests, revert to the last state where all the tests passed and reduce the number of refactoring steps before you run the tests again and commit.

No Tests - No Refactoring!

Before I show you how to apply the essential refactoring tools, I want to make clear that I assume that we have a strong and fast test suite in place, ideally unit tests, before we start refactoring. Else, we never know if we break something. If your code has no tests yet, you first need to create them. In a later article I will show you how to do that so stay tuned.

The 5 Essential Automated Refactoring Tools

There are only five automated refactoring tools your IDE needs to support to refactor effectively, which are:

Rename

The most powerful refactoring in our toolbox. Giving our variables, methods, or classes more expressive, context- and domain-specific names may already be enough to turn a completely unmaintainable piece of code into something easier to work with if we know the business domain this code is applied in.

Extract Variable

An essential tool in the refactoring toolbox is “extract variable”. It allows us to split a complex line of expressions, like those we may find in large and hard to understand if-statements, into smaller, more cohesive parts and give them domain-specific names. It is also often the prerequisite to split parts of the logic into smaller, cohesive modules, which is why it plays well with the next refactoring technique.

Extract Method

One of the most powerful refactoring techniques is “extract method/function”. In combination with extract variable, we can wrap small cohesive parts of the overall logic into methods with expressive, context-specific names.

Inline

Inlining means copy-pasting the content of a variable, method, or other form of module where this variable or method was used before. If it was used in multiple places, it may create duplications. It’s the inverse of extract variable or extract method. It is an essential tool especially in code with suboptimal abstractions, so that we can easily start out with a green slate and refactor towards a more maintainable solution.

Some IDEs like VSCode lack “inline” capabilities. However, it is absolutely essential to be able to try out different refactoring options quickly. I would always opt for an IDE like IntelliJ or Eclipse that supports “inline” out of the box.

Move

Extracting methods is not enough to improve the overall design. We also need to be able to split a long class or file into more cohesive parts and move parts to other files or classes. This is why it is extremely helpful if our IDE can automatically move methods to other classes. Although it can be done manually rather easily compared to extract variable/method or inline, I would still opt for an IDE that takes over most of the work as it’s just faster and safer to do so.

Lastly, an IDE should be able to create code automatically. For example, if we declare a new class using new, a simple shortcut should allow us to create that class in a few simple steps. Doing it automatically reduces the time spent and error probability a lot.

Shortcuts

To get you started more easily, I have compiled a list of all shortcuts for Mac and Windows for both Jetbrains (IntelliJ) and Eclipse so that you don’t have to figure them out all by yourself. You can download it as PDF here:

Refactoring Shortcuts (Jetbrains, Eclipse)

12KB ∙ PDF file

Download

All the shortcuts you need to refactor effectively

Download

Conclusion

Refactoring is a continuous process that we should be doing all the time while we develop software, not only in one big “refactoring story”.

To do so, we need to work in baby steps and commit after every green run of our tests. Without tests, we always run the risk of introducing bugs, so we need to ensure that we have a strong test suite.

There are 5 essential refactoring tools our IDE needs to support besides code generation - rename, extract variable, extract method, inline, and move.

Now that we know the essential tools for refactoring, we also need to know how to apply them effectively. I will dive into this in some of the next articles, so stay tuned!

If you want to test it yourself, you can find the code examples used in the video and post in the following repository (solution with steps on branch refactoring_basics).

Do you have any questions or remarks on the topic of refactoring code? Write a comment and we can discuss it further!

If you like content like that, don’t forget to subscribe to stay up to date!

Subscribe now

Want to learn how to write evolvable code? Visit our website www.codeartify.com and get in touch with us! We provide worldwide remote and on-site workshops for you and your team!

Want to know the importance of a rich domain model? Check out our comprehensive O’Reilly course on Domain-Driven Design, Clean Architecture, EventStorming, and TDD!

In this article, I want to briefly outline with a simple example that you can try for yourself why this idea can destroy your code’s ability to change effectively and cheaply.

A simple example

Test code should only change if the behaviour of the production code changes. We should not need to adapt test code just because we restructured the internals of our public API.

Let’s imagine the following simple codebase. A service “AService” has one collaborator “BService” which is called in AService’s method “invoke()”, as shown below.

public class AService {
    private final BService bService;

    public AService(BService bService) {
        this.bService = bService;
    }

    public String invoke() {
        // here is where the magic happens
        return this.bService.getHelloWorld();
    }
}

public class BService {
    private int callCounter = 0;

    public String getHelloWorld() {
        if (callCounter++ == 0) {
            return "Hello World";
        }
        return "World Hello";
    }
}

Let’s write a test for AService where we use Mockito to stub BService’s getHelloWorld() call, and a test for BService’s getHelloWorld() method.

public class AServiceTest {
    @Test
    void test1() {
        var mock = mock(BService.class);
        when(mock.getHelloWorld()).thenReturn("Hello World");

        var aService = new AService(mock);

        String result = aService.invoke();

        assertEquals("Hello World", result);
    }

    @Test
    void test2() {
        var mock = mock(BService.class);
        when(mock.getHelloWorld()).thenReturn("World Hello");

        var aService = new AService(mock);

        aService.invoke();
        String result = aService.invoke();

        assertEquals("World Hello", result);
    }
}

public class BServiceTest {
    @Test
    void test1() {
        var bService = new BService();

        var helloWorld = bService.getHelloWorld();

        assertEquals("Hello World", helloWorld);
    }

    @Test
    void test2() {
        var bService = new BService();

        bService.getHelloWorld();
        var helloWorld = bService.getHelloWorld();

        assertEquals("World Hello", helloWorld);
    }
}

So far, so bad. What if at some point we want to inline getHelloWorld() into AService because the call to AService.invoke() actually does nothing except delegating to BService.getHelloWorld()? Both our test classes break!

public class AServiceTest {
    @Test
    void test1() {
        var mock = mock(BService.class);

        // --------------------------------
        // automatic inline adds this
        // --------------------------------
        String result1 = "World Hello";
        if (mock.callCounter++ == 0) {
            result1 = "Hello World";
        }
        when(result1).thenReturn("Hello World");
        // --------------------------------

        var aService = new AService(mock);

        String result = aService.invoke();

        assertEquals("Hello World", result);
    }

    @Test
    void test2() {
        var mock = mock(BService.class);

        // --------------------------------
        // automatic inline adds this
        // --------------------------------
        String result1 = "World Hello";
        if (mock.callCounter++ == 0) {
            result1 = "Hello World";
        }
        when(result1).thenReturn("World Hello");
        // --------------------------------

        var aService = new AService(mock);

        aService.invoke();
        String result = aService.invoke();

        assertEquals("World Hello", result);
    }
}

Of course, BServiceTest’s test methods for getHelloWorld() can now be deleted as they aren’t used anymore. But AServiceTest’s test double for BService needs to be adapted. We need to touch test code even though we haven’t changed the behaviour of the invoke() method.

Now let’s look at an alternative scenario where we have no test class for BService but only a test class for the public API of AService that does not rely on test doubles but instead injects the actual BService.

public class AServiceBetterTest {

    @Test
    void test() {
        var aService = new AService(new BService());

        String result = aService.invoke();

        assertEquals("Hello World", result);
    }

    @Test
    void test2() {
        var aService = new AService(new BService());

        aService.invoke();
        String result = aService.invoke();

        assertEquals("World Hello", result);
    }
}

If we inline the BService.getHelloWorld() method, the test code looks as follows:

public class AServiceBetterTest {

    @Test
    void test() {
        var aService = new AService(new BService());

        String result = aService.invoke();

        assertEquals("Hello World", result);
    }

    @Test
    void test2() {
        var aService = new AService(new BService());

        aService.invoke();
        String result = aService.invoke();

        assertEquals("World Hello", result);
    }
}

You may have noticed: nothing changed! Only if we adapt the public interface of AService’s constructor to remove BService, we need to touch the test code. We can mitigate this problem by hiding away on what internal collaborators AService depends using e.g. a creation method on AService.

public class AServiceBetterTest {

    @Test
    void test() {
        var aService = AService.create();

        String result = aService.invoke();

        assertEquals("Hello World", result);
    }

    @Test
    void test2() {
        var aService = AService.create();

        aService.invoke();
        String result = aService.invoke();

        assertEquals("World Hello", result);
    }
}

public class AService {
    ...
    public static AService create() {
        // hide internal collaborators with creation methods
        return new AService(new BService());
    }
}

With this in place, we can change the collaborators in the create() method however we like.

Conclusion

Even this extremely small codebase demonstrates why we should avoid testing every “public” (or even protected or private) method of collaborators that are only used internally by other services in isolation, and “mock away” collaborators. If you want to call these “sociable unit tests” or “larger unit tests”, the idea behind it is that you mainly test the public, deep interface of the service that actually accomplishes something for the external caller and avoid coupling test code to production code.

You may think of your production code as a library. Which classes and methods are exposed to the public (meaning, are out of your control once they’re released because you don’t know who the caller are going to be?) and which only contain the “public” keyword because you need to access these methods by another method of another class?

In our experience, the most flexible test cases target only the publicly exposed API. We want to test any possible input we can receive by a public (out of our control) caller. If an input combination is theoretically possible in an internal method but cannot be executed from the public API, there may actually be no need to write a test for it.

In our tests, we should try to avoid creating test doubles for our own production classes whenever possible. We should reserve test doubles for awkward dependencies. These are dependencies that are slow, hard to instantiate, or nondeterministic, like file-system-, I/O- and network access, databases, random number generators, time, etc. Any other class we have control over should be instantiated directly so that we can freely refactor the internals of our code without having to adapt any tests! Only if the actual behaviour changes should we need to touch a test.

As always, this is only a rule of thumb and there are many exceptions.

Sometimes it is not possible to test without test doubles, and sometimes our internal class is complex and has many edge cases that need to be covered by an own test class file.

But it should always be a deliberate decision to create test doubles or to test “internal” “public” methods.

If you want to test it yourself, you can find the code examples used in the this repository.

What do you think? Do you agree or disagree? Do you have other experiences to share that show the importance of mocking collaborators even if they are not awkward? Write a comment and we can discuss it further!

If you like content like that, don’t forget to subscribe to stay up to date!

Subscribe now

Want to learn how to write evolvable code? Visit our website www.codeartify.com and get in touch with us! We provide worldwide remote and on-site workshops for you and your team!

New to Domain-Driven Design, Clean Architecture, EventStorming, and TDD? Check out our comprehensive O’Reilly course on that topic.

"We have Scrum Masters, Agile Coaches, Team Coaches, and now Technical Agile Coaches? Is there actually still somebody around who works productively?" I hear you say. But let me explain.

The idea for my interpretation of a "Technical Agile Coach", which subsequently will be referred to also as TACo, came to me when I first heard of Samman Technical Coaching, a coaching technique developed by Emily Bache. The main idea is simple - as part of a development team, a TACo works together with the entire team and individuals on improving their agile software engineering skills.

These skills include, but are not limited to: eXtreme Programming, Refactoring, Testing and Test-Driven Development, identifying and solving Code Smells, software design like Hexagonal or Clean Architecture, Event Sourcing, CQRS, strategic and tactical Domain-Driven Design, EventStorming, Story Writing & Slicing, effective Aggregate- and Monolith/Microservice-sizing, and many more. Teams have typically heard of these topics, but because there are so many things a modern software engineer needs to know (frameworks etc.), understandably, they do not always have the time and energy to invest in these methodological topics as well as much. Yet, they are key to effectively develop software.

Practices are taught in 1 - 2 hours called Learning Hours, which can be bi-weekly, weekly, every other day, daily, or even more frequently, depending on the need. Practices should be introduced depending on the interests and needs of the entire team. During Ensemble - or Pair Programming sessions, small groups or team members can address their interests and potentials for improvement individually. There is no obligation - every team member decides for themselves how much involvement they want with the TACo.

A TACo, on the other hand, can step-by-step help building up these skills on the job, while the team is productively developing software. By the end of a mandate, the understanding and skills of the team will have significantly broadened. Compared to singular (multi-day) workshops with little retention, continuously practicing technical software development skills is more likely to form long lasting habits.

A TACo a Day keeps the Doctor away

However, a TACo does not only address technical skills. A development team can technically excel, yet be riddled with unresolved internal problems and external pressures that can destroy all the good work done so far.

As such, technical agile coaching is an effective approach to identify and address the actual, underlying blockers of a team. As part of the team, a TACo feels the internal quarrels and outside pressures, but because they are not immediately involved in productive work, they are in the unique position to address issues without being directly affected. As a consultant to the team, a TACo may point out potentials for improvement, but the team is free to decide to pursue them (immediately) or not.

"Technical Agile Coach" is also not a typical "leader" role. There is no hierarchical structure in place as the TACo is neither above nor below, but besides a team's and an organisation's hierarchy. Any team member from junior to senior over PO to ScM can seek inputs from a TACo without fear of influencing their career in any way. Anything mentioned in personal conversations is handled confidential unless team members want actions to be taken.

Of course, this does not imply that a TACo should ignore pressing issues like mobbing or company-harming practices! On the contrary, due to their unique position, they are able to identify and address such issues even earlier within the team and provide guidance or get input from outside without escalating the entire situation out of proportion.

Best TACo Recipe

Overall, technical agile coaching is not an imposed, top-down approach. Neither is it a "visit, fire and forget" approach, where a TACo only shows up for some workshop without any investment in the team and then leaves again. It requires both a high degree of technical understanding, hard programming skills, but also the abilities to "feel the room" effectively, avoid position taking, and adapt one's manners according to each individual team member. TACos enable the team to work better individually and collectively.

The highest value of this role comes from the deep involvement within the team, while being detached from outside influences and pressures. TACos should therefore always be treated as separated from the hierarchical organisation of a company, as an incorporation into it would defeat the purpose of the role.

As a young role, its effectiveness cannot be put into numbers yet. But the close involvement of a TACo within a team with a steady focus on identifying root causes of problems and developing a team-tailored set of possible solutions, should logically lead to a more effective outcome than one-time workshops or presentations with only little team involvement.

Additionally, this role provides an interesting career opportunity for any developer that does not want to pursue a purely low-level, technical path, but at the same time does not want to leave the technical aspects behind entirely in favour of a classic leadership role, either. It involves skills from all the different roles, from Scrum Master to Agile Coach to Developer to Tech Lead and Architect and even PO, as well as a high degree of social skills. It's for skilled generalists who are interested in various topics and the global picture.

Furthermore, TACos are connected throughout the company and can bring in required skills from outside the team if needed. They should best be deeply connected outside of the company and internationally as well to always stay up to date and be able to exchange and learn from various other experts, approaches, views and ideas.

It's more than a job, it's a calling.

If you want to learn more about my approach on technical agile coaching, just DM me, e.g. on Linkedin. If you want to exchange with a TACo for your team’s specific needs, we at Codeartify are happy to take on the challenge as well! See you soon!

You may have heard the terms "Hexagonal Architecture" or "Ports and Adapters", coined by Alistair Cockburn, in some form or another. It's an architectural design pattern that places the business rules at its core. The idea is that the business rules are what defines a company, not technical details like what kind of presentation or database technology is used. But how do we get from a classic layered architecture to Hexagonal Architecture? 

Layered Architecture in a Nutshell

In a classic layered architecture, we typically find the following layers: Presentation --> Application --> Data Access. Upper layers depend on lower layers. All the layers however, depend on the data access layer.  This means that if we change the data access technology, say from SQL to an external system, we need to adapt the code of layers above, even though they did not change in functionality. 

@RestController
class RestCustomerController {
  CustomerService service

  @PostMapping("/customer/name")
  CustomerDbEntity changeCustomerName(CustomerDbEntity dbEntity) {
    return service.changeCustomerName(dbEntity);
  }
}

@Service
class CustomerService {
  SqlDbClient client

  public CustomerDbEntity changeCustomerName(CustomerDbEntity input) {
    CustomerDbEntity entity = client.execute(
       "select * from customer where id="+input.id);
    CustomerDbEntity result = applySomeBusinessRules(entity, input);
    return client.execute(
        "update customer set name =" +result.name +" where 
        id="+result.id);
  }
}

From Layered to Hexagonal Architecture in 2 Steps

Now, let's see how we can transition from this layered architecture to a hexagonal architecture.

Step 1 - Invert the Dependencies of the Application Service to the Data Access layer

The first step is to make the data access layer depend on the application layer, not the other way around. We can achieve this by introducing an interface that only uses application-specific data structures in its signature for CRUD operations. For that, a Customer class may be created, which could typically be a domain class that can also execute critical business rules. The important idea here is that the signature of the interface does not contain any CustomerDbEntity. The interface is application-layer specific. It's the first output port that is used by the CustomerService to load and store Customers. On the other hand, SqlCustomerRepository needs to implement this interface. It takes a Customer object, maps it to the CustomerDbEntity, invokes the db client, and potentially maps the CustomerDbEntity back to a Customer. Thus, it adapts the DB data structure from and to the application-specific Customer data structure. It's an adapter. Also, the service does not use CustomerDbEntity in its public method signatures anymore, but only simple application-layer-specific DTOs like CustomerData that get passed to and returned from the service. In pseudocode:

interface CustomerRepository {
  Customer getById(String id);
  Customer update(Customer customer);
}

@Service
class CustomerService {
  CustomerRepository customers;

  public CustomerData changeCustomerName(NameData input) {
    Customer customer = customers.getById(input.id);

    customer.changeNameTo(input.name);

    Customer updatedCustomer = customers.update(customer);

    return toData(updatedCustomer);
  }
}

@Repository
class SqlCustomerRepository implements CustomerRepository {
  SqlDbClient client;

  Customer getById(String id) {
    CustomerDbEntity entity = client.execute(
        "select * from customer where id="+input.id);
    return toCustomer(entity);
  }

  public Customer update(Customer input) {
    CustomerDbEntity entity = client.execute(
        "update customer set name =" +result.name +" where 
        id="+result.id);
    return toCustomer(entity);
  }
}

We could now easily implement a fake CustomerRepository for testing purposes:

class InMemoryCustomerRepository implements CustomerRepository {
  Map<String, Customer> customers;

  Customer getById(String id) { return customers.get(id); }
  Customer update(Customer customer) {
    customers.put(customer);
    return customer;
  }
}

Step 2 - Segregate the Public Methods of the Application Service into Separate Interfaces

The second step involves hiding away how the different public methods of a generic application service are implemented from the presentation layer. This could be useful if we wanted to split a larger service into smaller use cases. By adding an interface for every public use case method that the CustomerService provides, and letting it implement them all, the RestCustomerController gets more fine-granular methods to execute. The controller may or may not use an own DTO instead of the data structures provided by the application layer in the CustomerService's public methods. That way, it may evolve independently from the application layer, for example if not all the fields need to be returned or they should be formatted already on the server, etc. These interfaces correspond to input ports, and the controller is a driving adapter that maps incoming data to the input port's data requirements, executes the functions of these ports, and maps data back to the caller's data format. In pseudocode: 

interface ChangeCustomerName {
   CustomerData changeNameTo(NameData name);
}

interface ChangeCustomerAddress {
   CustomerData changeAddressTo(AddressData address);
}

interface ChangeCustomerProfile {
   CustomerData changeProfileTo(CustomerProfileData profile);
}

@RestController
class RestCustomerController {
  ChangeCustomerName changeCustomerName;
  ChangeCustomerAddress changeCustomerAddress;
  ChangeCustomerProfile changeCustomerProfile;

  @PostMapping("/customer/name")
  CustomerDto changeCustomerName(NameDto dto) {
    NameData data = toData(dto);
    CustomerData customer = changeCustomerName.changeNameTo(data);
    return toDto(customer);
  }

  @PostMapping("/customer/address")
  CustomerDto changeCustomerAddress(AddressDto dto) {
    AddressData data = toData(dto);
    CustomerData customer = changeCustomerAddress.changeAddressTo(data);
    return toDto(customer);
  }

  @PostMapping("/customer/profile")
  CustomerDto changeCustomerProfile(ProfileDto dto) {
    ProfileData data = toData(dto);
    CustomerData customer = changeCustomerProfile.changeProfileTo(data);
    return toDto(customer);
  }
}

@Service
class CustomerService
  implements 
  ChangeCustomerName, ChangeCustomerAddress, ChangeCustomerProfile {

   @Override
   CustomerData changeNameTo(NameData name){...}
   @Override
   CustomerData changeAddressTo(AddressData address) {...}
   @Override
   CustomerData changeProfileTo(CustomerProfileData profile) {...}
}

That's it, basically

The controller adapter now uses any of the three input ports of the application layer and does not know of the CustomerService anymore, which implements the 3 port interfaces instead. Similarly, the CustomerService only uses output ports and does not know of the SqlCustomerRepository and only interacts with the output port interface CustomerRepository methods. There is even a Customer class that can be used to implement critical business rules on, which could be stored within an own "domain" layer. The domain layer is not strictly Ports & Adapters anymore but actually Domain-Driven Design. Data access and presentation now depend on the application layer. All dependencies (arrows) point towards this application layer. This is why hexagonal architecture is a business-centric architecture. The different data structures may feel like an overkill for simple applications - they are. Their value comes especially in complex architectures, where presentation, application, and data access layers change independently, often. They are not required by Ports & Adapters either, as long as the application does not depend on any data structure from the outside world. It can only know internal data structures.

What do you think about this architectural design pattern? Have you used it? To what success? What downsides do you see?

Share