DEV Community: Carlos Gándara

Taking advantage of CQRS in legacy applications

Carlos Gándara — Thu, 11 Sep 2025 08:31:45 +0000

When we think about Command Query Responsibility Segregation (CQRS), chances are our mental model is the one for an application built around dispatching events in a write model, process them to update a read model, event stores, message buses, projections,...

In this post we will explore how we can benefit from CQRS without all that tooling, which may seem impossible to introduce in legacy systems. To do so, we will explore Pattern CQRS as a low level approach to differentiate command and query operations.

I will refer to operations or use cases that change state as command or write. After one of these, the system is different as it was before. Example: activate a new user.

For operations or use cases that read data I will use query or read. No matter how many times you run them, the system stays unchanged as the operation has no side effects. Example: listing all users.

Architectural CQRS vs Pattern CQRS

CQRS in its essence is about separating the code responsible of changing state from the code responsible of reading data. Which is literally what the pattern name means.

This separation may influence the whole application architecture or apply at a more granular way. Both options with their ups and downs.

Note Architectural and Pattern CQRS are just names I made up for this post. This is not standardized terminology.

Architectural CQRS implies the architecture is built around it and maximizes the pattern benefits. In exchange, it requires specific tooling (like the mentioned before: events, buses, etc.). Since changing the architecture of an application is usually a costly process, even when iteratively, applying this approach to existing codebases may mean a significant effort.

Pattern CQRS is a lower level thingy, and therefore easy to apply in a case-by-case basis. Therefore, it will be probably easier to refactor an existing application with this approach, even when the benefits are coming in smaller bits.

There is this excellent post from Alberte Mozo, explaining the pattern initial formulation and how none the architectural or pattern approaches (and everything in between) are necessarily better or more pure, if being pure is even a relevant thing.

Here we are interested in Pattern CQRS in a brownfield project, and we will use a simplified example to illustrate it.

A familiar scenario

Let's assume an existing codebase with the following:

The application is organized in use cases.
There is some abstraction to fetch entities from our domain model, like repositories.
The entities are modeled to cover both command and query operations.
Some read operations involve many entities.

For instance, we have a use case to activate users and another one to list all users. The User entity is used in both, but listing users requires to show the subscription plan users have so we need to involve the Subscription entity for the listing as well.

class User {
    public function __construct(
        //Many other properties
        public string $email,
        private Status $status,
    )

    public function activate(): void {
        if ($this->status->canBeActivated()) {
            $this->status = $this->status->toActive();
        }
    }

    public function getStatus(): string {
        return $this->status->toString();
    }
}

class Subscription {
    public function __construct(
        //many properties unrelated to listing users
        private Type $type,
    )

    public function typeAsString(): string {
        return $this->type->asString();
    }
}

The activation use case is a command and uses User to change state:

class ActivateUser {
    public function run(
        UserRepository $userRepository,
        UserId $userId
    ): void {
        $user = $userRepository->getWithId(userId);
        $user->activate();
    }
}

While listing users uses both entities as the data required is scattered among them:

class ListUsers {
    public function run(
        UserRepository $userRepository,
        SubscriptionRepository $subscriptionRepository,
    ): ListUserCollection {
        $users = $userRepository->findAll();

        $response = new ListUserCollection();        
        foreach ($users as $user) {
            $userSubscription = $subscriptionRepository->forUser($user->id());
            $response = $response->add(
                [
                    'email' => $user->email,
                    'subscription_type' => $userSubscription->typeAsString(),
                    //many other fields
                ]
            );
        }

        return $response;
    }
}

There are a number of potential problems here.

Entities are messed up. They cover both types of operations and chances are some of their properties are there just to show data, while some others are used also to perform business logic. The properties used for reading data use cases are accessible either via getters or public properties in order to return some response. This breaks the encapsulation OOP principle and harms the ability to refactor and evolve our domain model. Not to mention that the entities are bloated with properties not intended for business logic.

Our example is simplified, but we can assume User has far too many properties. Subscription as well, and it's specially painful here because we only care about the string representation of the type from it. We need to include getters for a string representation of user status and subscription type, which makes changing them more complex than being an internal concern of the entities.

Another potential problem is performance and wasted resources. Overall, read use cases are expected to be served faster because there is somebody waiting for a response in the other side of the wire. Since we use entities to access data, a read use case may require many of them to pick just small bits from each. Entities will include many other properties that are irrelevant for the current needs, but the resources and time are invested to fetch them anyway.

In our example, if building a Subscription requires many joins at database level, we are incurring on that overhead just to get the type.

CQRS benefits

By applying CQRS we prevent the above issues by creating different models for the write and read operations. Entities are freed of read-only data and we introduce a separate read model that is only a data structure with no business logic involved.

Our write model can evolve in a more flexible way because there are not extra properties and the amount of public interface exposed is reduced.

The read model is ad-hoc for the query use cases and the data access operations can be optimized for faster responses.

Both Architecture and Pattern CQRS help for a better entity modelling, while the optimized reads are way more powerful in Architecture CQRS than in the Pattern version, which may still require some query gymnastics to access all the data.

Implementing Pattern CQRS

In Architecture CQRS the write model (the entities) publish events when there is a state change. These events are processed to update the persistence dedicated to the read model only and to read operations we use simple SELECT queries. We can even use a different persistence technology to favor read speed. As commented, it influences the whole architecture and needs specific tooling to accommodate it.

In Pattern CQRS we give up some of the benefits of the Architectural version, but its implementation is more straightforward. Introducing it in existing applications is overall simpler and gives immediate benefits.

Create a new model for the read use cases consisting only of the data they require.
Create a new data access abstraction that fetches this model.
Replace the usage of the write model repositories with the new abstraction, and use the read model to produce the response.
Profit.

Applied to our example, the activate use case stays the same but the read is simplified to:

class ListUsers {
    public function run(
        ListUsersQuery $query,
    ): ListUserCollection {
        return $query->findAll();
    }
}

Since the ListUsersQuery will take care of doing the query to get the exact data needed.

The User entity no longer requires data intended to read operations and has a smaller public interface:

class User {
    public function __construct(
        //Other properties, but none for read operations
        private Status $status,
    )

    public function activate(): void {
        //same as before
    }
}

Changing its internal representation involves less changes since it's not exposed anymore.

Upsides

As we see in our naive example we don't need to change the command use cases, and for the query use case we introduce a new model and the abstraction to get it from persistence. This can be done in an iterative way and with a reduced amount of changes introduced each time.

While we migrate read use cases to Pattern CQRS, we can incrementally get rid of unused properties in our entities. They become less verbose and include only data used for command operations. A smaller public interface means better encapsulation and makes refactoring and evolving them easier than with a bigger public surface.

Actually, the more we attach entities to read operations the more we are inclined to mimic the database when designing them, which harms the domain design flexibility. CQRS helps to reduce that temptation.

The performance can potentially improve as well, reducing the queries to fetch only what we need.

Finally, by applying Pattern CQRS we end up with a use case design prepared to transition to Architectural CQRS easily since the read use cases will be basically the same (many other changes are needed, but in other places; the transitions is easier but not trivial)

Downsides

There is always a tradeoff and Pattern CQRS is no exception. We used a simple example in this post, but sometimes (always) reality is not that straightforward.

If our read use case requires data that is computed through business logic, we would need to fetch the entities anyway to run the calculations (or to replicate the business logic in the queries, which is a very bad idea).

For instance, if listing orders shows the order total and this value is not persisted but calculated in the Order entity (by adding each order line total, apply taxes, discounts, etc.) we will need to fetch and use Order to build our response.

We should evaluate whether adopting CQRS is worth the effort, as it may reduce clarity and even degrade performance due to fetching entities on top of the read model.

From a maintenance perspective, by adopting Pattern CQRS we are introducing a new model without fully breaking the persistence coupling between write and read models. We should expect certain maintenance overhead. Simple domains without relevant business logic may be totally fine mixing up write and read data since they tend to not change much, and we may be investing resources in a separation that may not reap any benefits.

Conclusion

We have seen how we can benefit from CQRS by introducing it in existing applications without a big bang architectural change. How beneficial this can be should be analyzed in each case, since it is not a silver bullet, and it can sometimes do more harm than good.

If you, as it happens to me, are annoyed by unreadable entities cluttered with getters and so attached to the database design that it is cumbersome to evolve them, consider giving Pattern CQRS a try. A single well-chosen use case refactor can show the potential of it right away and convince skeptics and those wary of over-engineering.

Cover image by PetarM, under Creative Commons Attribution-Share Alike 4.0 International license.

Understanding clean architectures

Carlos Gándara — Mon, 09 Sep 2024 10:07:25 +0000

The clean architecture concept was introduced by Robert C. Martin back in 2012. He later published a well known book about it with the slightly lazy but straightforward title Clean Architecture.

In this post we will cover the foundations behind this architectural pattern.

It is worth mentioning that I have not read the book. Therefore, the following content is not based directly on it but in its underlying concepts.

TL:DR;

In a clean architecture the application is divided into layers, assigning concrete responsibilities to each of them.

Those layers wrap each other and communicate only inwards: an outer layer can use stuff from inner layers, but not the other way around. This is known as Dependency Rule.

The more outward a layer is, the lower-level its responsibilities are. The innermost layer takes care only of the higher level details: the domain model.

That's basically it when it comes to how this architectural pattern structures things. The how.

It is only by knowing the why behind it that we will understand what we get in return and when it is worth to use it.

Software purpose

We create software to solve problems. We should at least. If it's not the case, please spend a bit of reflection on what we want this world to be and what are we doing to achieve it. Anyway. Solve problems.

To solve a real world problem with software, we create a model that represents part of the real world that helps us to tackle its complexity.

Software does not only have to deal with just the problems it solves, though. It runs in computers, it's written in a language, uses networks, servers, protocols...

If we mix together all these technicalities with the problem model, we are putting a spoke in our wheels by making the model and the technical part more complex than they actually are. Which is something we usually want to avoid. Clean architectures help keep separated the stuff that do not belong together.

Before moving forward with the clean architecture itself, we will take an interlude to talk about complexity and cognitive load, concepts tightly related to the goals of clean architectures.

Complexity is all over the place

Complexity is, oversimplifying, how hard it is to grasp how all the moving parts of a system work together.

More complexity means more effort is required to understand, maintain, and extend a software system. This effort is known as cognitive load.

Therefore, keeping cognitive load low by removing complexity is a good thing to do. Easier said than done, because complexity cannot be removed in its entirety.

There are two types of complexity: essential and accidental.

The essential complexity is intrinsic to the problem we want to solve, and it's there no matter what. It cannot be eliminated. Not even reduced.

For instance, in an e-commerce we cannot realistically say "no, rejected payments are not a thing for us". Certainly life would be easier without them, but the reality is payments are sometimes rejected. This complexity is essential to the problem our application solves.

The accidental complexity is what we humans, in all our messiness, add to things, consciously or not, making things harder than they essentially are. We cannot escape it, it's part of the human nature. We can, though, stay vigilant and mitigate it as much as we reasonably can (or want).

A blatant example of accidental complexity would be adding load balancing and database sharding to an application intended to manage a small dental clinic. The application does not need that, and it makes harder to understand it.

A more subtle example would be, in our previous e-commerce application, to mix up technical details like HTTP requests and the database table relations needed to fetch data, with the domain logic needed to manage something already complex enough like payments. By not keeping those different concerns separated, we are making both parts harder to understand.

What for

Now that we have agreed on some definitions, we can state the purpose of a clean architecture:

To keep our model of the real world separated from technical details, so we avoid introducing accidental complexity in both sides.

In other words, to reduce accidental complexity by keeping the essential complexity of running software separated from the essential complexity of the problem solved by the software.

Clean architectures structure applications in a way that helps us to keep the accidental complexity (a part of it at least) under control.

The layers

Layers are groupings of responsibilities. There can be any number of them at code level but attending to its purpose they boil down to three.

👉 Indeed, the original post where the pattern was presented includes four layers. Which to my understanding is an implementation-level decision rather than a purpose-level grouping. Like with everything else, I'm just a guy with an opinion on the internet. Read, ponder, and build you own understanding without blindly follow anything.

In a clean architecture, we visualize layers as concentric circles (or half a circle to optimize space, he). The more we move inside, the higher level of detail the layer takes care of.

The outermost layer is the Infrastructure Layer, connecting the different technologies the application interacts with in the way the inner layers require. This is the lower level of detail our application has to deal with, technology specific stuff like HTTP headers, the format of request payloads, databases, etc.

Next is the Application Layer (also known as Service Layer), holding a representation of the use cases the application exposes and taking care of orchestrating the execution of the right logic for the use case requested. It manages a higher level of detail by knowing the logic a use case needs, without any technical details involved.

👉 The Application Layer does not need to always orchestrate Domain Layer logic, although it may seem so from the usual diagrams used to represent a clean architecture. For instance, use cases for plain read operations may not require any business logic.

The innermost one is the Domain Layer, where our model of the problem to solve lives. This is the highest level of detail. By keeping our domain model isolated from the concerns of the Infrastructure and Application layers, we can approach its complexity without distractions, making it easier to evolve and change.

👉 The framework we use to run our application is an infrastructural concern as well. We can think of it as if Application and Domain code is "portable" and should require no change if we switch to another framework.

The Dependency Rule

The Dependency Rule defines the visibility between layers. It states that a layer can only depend on inner layers, never in outer layers. In other words, a layer cannot have code references to anything that is declared in an outer layer.

What we achieve with the Dependency Rule is that no details of a layer leak into the others. By applying inversion of dependencies (the "I" in SOLID), inner layers define abstractions that outer layers implement. The abstraction is defined by the inner layer, and therefore sticks to its level of abstraction, and it's not polluted by lower level details.

The classic example are Domain repositories. At Domain level we define an interface which is implemented in the Infrastructure layer. But this interface sets a contract expressed in Domain language, with no technicalities involved. In the Infrastructure layer, the implementation will take care of mapping the data to the right tables, which are lower level details that should not concern the Domain.

Anatomy of a clean architecture

It's about time we come with somewhat practical examples after all this theory.

In the Domain Layer we have our domain model, an abstraction of the real world problem. The design may not be the best, but it's good enough to illustrate how the thing works:

interface PaymentRepository {
    fn findById(PaymentId id): Payment
}

class Payment {
    private Status status;
    private RejectionDate rejectedOn;

    fn reject(Date when) {
        status = Status.rejected();
        rejectedOn = RejectionDate.fromDate(when);
    }
}

Our domain model is written in pure domain language. There are no references to databases, HTTP requests, message queues or any other technology. Neither there are references the framework.

When we go to the code to see what rejecting a payment means, the code tells us directly, and we do not need extra cognitive load to separate the business logic from other unrelated details. Analogously, the PaymentRepository is a contract the Domain defines in its own terms. The implementations will live in the Infrastructure, dealing with the technical details of the technologies used.

At the Application Layer we have the use case that represents a payment must be rejected:

class RejectPaymentUseCase {
    fn RejectPaymenUseCase (
        private PaymentRepository repository,
        private Clock clock
    );

    fn execute(RejectPayment request) {
        payment = repository.findById(PaymentId.fromValue(request.paymentId));
        payment.reject(Clock.now());
    }
}

The Application Layer just orchestrates the logic needed to fulfill the "reject payment" use case. It does not know what it means at business level, only what must be executed to do it. Analogously to the Domain Layer, there is no interference from technical details.

It is in the Infrastructure Layer where we find technical references:

class RejectPaymentHttpController {
    fn RejectPaymentHttpController (
        private RejectPaymentUseCase useCase
    );

    fn execute(HttpRequest request): void {
        payload = JsonHelper.deserialize(request.payload);
        useCase.execute(
            new RejectPayment(payload.paymentId);
        );
    }
}

class SqlPaymentRepository < PaymentRepository {
    fn findById(PaymentId $id): Payment {
        //details of database tables, prepared statements and other DB stuff
    }
}

The entry points to the application are the ones that handle the low level details of the underlying technology. In this case the HTTP controller knows about HTTP requests, deserializing JSON payloads, etc. Same for the repository implementation: at Application Layer level, the use case knows nothing about the persistence details of a Payment, it just knows the contract the Domain Layer defines.

👉 Contracts can be defined by Application Layer as well, it's not an exclusive treatment for the Domain.

While adhering to the contracts specified by inner layers, they prevent this complexity to leak into layers with different purposes.

In this sneak peek into what a clean architecture looks like we have deliberately used a quite simple example. There is way much more to it. The purpose of this example is to just show how the layers are taking care of their own concerns, liberating other layers of extraneous details.

Real life™️ will require a much more complex implementation because there are many more things to model and take into consideration: message buses, event driven design, the outbox pattern, CQRS, configurations and environments... the list is huge. Some stuff is optional, some other contextual. But rest assured there is more and the above is not a blueprint to start with.

Humans after all

As with every pattern, it is up to us to be consistent with it. In case of clean architecture there is no standard implementation (unless you take the one from Robert C. Martin as such... just be aware there are other valid options).

The most common pitfall when going clean is to make the Application Layer too smart, leaking Domain logic in our use cases instead of just using the right parts of the domain model. And that's something the architecture cannot prevent.

It would be also tempting to make the Infrastructure Layer to run some domain logic to get a persisted entity into a certain state.

Or to introduce technical details into the domain model because it seems convenient.

While I would discourage to do any of this, it might make sense under certain circumstances. It is our decision to contravene the architecture foundations at a given moment.

At this point we should already have the understanding of what we are giving in exchange. And that probably the transgressions should not stay there for long.

When and when not

There is a trade-off. There always is.

As we have seen, there is a level of essential complexity in a clean architecture itself. Not only knowing about the layers, their responsibilities, and the Dependency Rule. There is also all the extra salt we can or must add for the architecture to actually do the work.

Turns out in our attempt to reduce complexity we are adding more complexity. What a world!

So when does it make sense to use clean architectures? The math is simple: when the problem we are solving is complex enough on its own that the additional complexity introduced by clean architecture is outweighed by what we gain in return.

Clean architectures will work best when we are dealing with the core domain of our business. This is usually complex enough to compensate the effort of having such an architecture. We want our core to be easy to iterate, and clean architectures are good at that by keeping the domain model isolated. Not so critical parts of the system may not be worth the effort. When the problem is not complex enough a more dirty approach can suffice for the same effectiveness with a lower effort.

In our e-commerce example we have seen payments are complex and a clean architecture pays back. But something accessory like the comments of products might be simple enough so that a hardcore-framework MVC approach will provide the same result in less time with no perceptible penalties.

Architectures are chosen to support our needs. If the needs change, maybe an architectural change is required as well. If our comments subsystem becomes a differential part of the business and grows in functionalities and complexity, our good old MVC system could become overwhelmed, and we will need to transition to a different architecture to support it. Maybe a clean one. Embrace the change!

👉 It could make sense that within the same application we may go clean for part of it and use another architecture for the less complex use cases. Symmetry has its advantages: if everything works the same way, it's easier to understand. But is it worth all the indirection for the most basic use cases? Well... it depends.

What is not

Clean architecture is not a synonym of Ports and Adapters (aka Hexagonal Architecture). Neither it is a synonym or a requirement for CQRS, Event Sourcing, Event Driven Architectures, or Domain Driven Design.

It is possible to go with any of those without a clean architecture. Although clean architectures are great friends of those other patterns.

Concluding

We should have now a clear understanding of the principles behind clean architectures (or, at least, my version of them).

We didn't dig much into implementation details, though. There is a lot to say about it. Reading about the message bus and the command + command handler patterns is a good follow-up to take the most out of a clean architecture, along with approaches that focus on domain modeling, like Domain Driven Design.

That's all. Feedback is always welcome so drop a comment if you want.

Be kind. And as happy as possible.

The cover picture is the science library of Upper Lusatia in Görlitz, Germany. The photo was taken by Ralf Roletschek (Roletschek.at), who holds the copyright, and it's available at Wiki Commons

Structuring Modular Monoliths

Carlos Gándara — Mon, 11 Dec 2023 14:56:14 +0000

A monolith is a self-contained software application responsible for the whole set of functionalities of a system.

It is a term with negative connotations. Not because there is an inherent flaw in it, but because of the context surrounding it. Which most of the time is that the company growth was not balanced with appropriate architectural design.

In this post we will explore a way of structuring monolith applications that avoids the most common pitfalls associated with this way of building and shipping applications.

Following there are a number of guidelines to have a healthy monolith. Even when the naming or the language used seems to refer to absolutes, the value is in what we want to achieve with each decision. There are many ways to get there and here we just describe one.

The ugly monolith

Monoliths are often associated to the (un)architectural pattern named big ball of mud. The usual stinky stuff we find there is:

Everything is accessed by everyone, everywhere.
Persistence is shared across all the monolith.
A trend to have god objects and over-abstractions.
The framework is everywhere, there is no isolation from it or for other vendor libraries.

Although it's true a distributed system would mitigate some of these problems, it won't be guaranteed and for sure not for free. There is little correlation between these disturbing circumstances and shipping our application as a one or many units. A messed up monolith is a messenger. Instead of blaming the messenger, we could better try to understand the message and get out of the mud.

How? Structuring our monolith it in a way that fosters separation of responsibilities and defines clear boundaries between the different domains it includes. Monoliths can be nice.

The modular monolith

A domain is "an area of knowledge or activity".

We call module the aggregation of all the code that takes care of a certain domain -or a group of domains- within our monolith.

In a modular monolith:

Modules are the high level organizational units. Although they live withing the same monolith, we manage them as if they were isolated applications.
They have limited visibility of each other. We cannot call arbitrary parts of a module internal implementation, avoiding the high coupling this implies.
Each module has its own persistence layer. So changes in a module data schema do not directly affect others.
A module is ideally own by a single team. Otherwise, Conway's Law will manifest and the need to communicate between the teams will result in a module sneakily split into two.
Modules communicate via direct code calls, controlled by each module, or messaging. Both ways are explicit. Each module controls its own boundaries.

For instance, in an e-commerce application we could have domains like Product Catalog, Order Handling, Payments, Shipping, etc. Sometimes, depending on the concrete case, we will have a module for each of them, or we may decide it's a good idea to group together Order Handling and Shipping if they are closely related.

The Product in the Product Catalog module will not be polluted by Order Handling related actions. Order Handling will have its own independent Product model.

To query product data, the Product Catalog module will expose a client with a defined contract for doing so (code call communication). To inform a new product was created, the Product Catalog module will publish a message in a shared bus (messaging communication) so other modules can react to it.

Which modules?

Figuring out the right modules is no easy task.

We must take our time for doing domain discovery and come up with a reasonable structure of modules. Chances are they won't be right in the first attempt. Software is an ever-changing thing, and we will need to rethink and adjust our modules to reflect that. Which is fine. The intention of this post is not to cover that specific aspect, though.

Techniques like Event Storming, Domain Storytelling, or Context Mapping can help with the domain discovery and identifying our modules.

High level organization

This is how the high level structure of a modular monolith could look like (the numbers in the left means belonging to the same organizational element):

#1 .github/
#1 .docker/
#2 docs/
#3 src/
#3    Module1/
#3    Module2/
#3        Module2A/
#3        Module2B/
#3    Module3
#4    ModuleBus/
#5    Boilerplate/

#1 In the root we have the general operational stuff. Note we don't have shared dependencies, as they are defined at module level.

#2 There is space for transversal documentation. Besides docs on how to set up environments, pipelines, deployments, etc., this is the right place to document guidelines on the architectural styles to default to (more on this in a moment).

#3 Inside src we set a high level structure that tells us first sight what are the different activities our system covers. Nesting modules is fine for a more meaningful grouping, although there is no shared code in a parent module.

#4 #5 There are two eyebrow-raising artifacts, though. ModuleBus and Boilerplate

ModuleBus goal is to provide lightweight tooling for modules to publish messages that could be consumed by other modules, in a pub-sub fashion. All modules have access to it. More details in a moment.

Boilerplate is an intentionally terrible name for what we usually see as Common, Shared, or Utils: tools or models we don't want to repeat over and over... unless maybe we do want?

"Base" models seem a convenient and harmless thing to have. However, if there is free access to them from everywhere in the monolith they tend to attract new concrete aspects that are required by just on module. This tends to cause over-abstractions to make room for too many parties interests, and recurrent breaking changes caused by the high coupling of many moving parts to the same shared code.

The proposal here is to not allow direct usage of Boilerplate code. The shared libraries and models are there, but cannot be used directly. Instead, modules copy the shared stuff they need in their own Boilerplate namespace and use their own version, which can evolve -or not- without interfering with other modules.

Module internals

In each module we will find some common artifacts and the module implementation itself.

src/
    Module1/
        [module implementation]
        Client/
        Messaging/
        docs/
            adr/
                adr1.md
                adr2.md
                ...
        dependencies.json

For the implementation we will do whatever makes sense, being it a clean architecture, a full framework one, or whatever else. The complexity of the domains, among other factors, will dictate it. Being modular does not mean we cannot choose the most appropriate architecture for each module.

Dependencies are defined per module as well. This allows each module to use its own toolset and not get restricted by the module that take more time to upgrade, preventing the use of more recent dependencies.

Modules have their own documentation. Remember we mentioned adding general architecture guidelines in the doc at root level? The module doc is the place to confirm they are followed or not, along with the reason for changing anything and what the change is. Architecture Decision Records are a great tool for that purpose.

In the area of common artifacts, we have the Client and Messaging namespaces, used for the communication between modules.

Talking with the outside

Since we treat each module as a separate application, when the time comes to communicate with other module we should assume it is somewhere else, like there is a network in between. Therefore, is each module defining what others modules can do and how to do it.

Code call communication

One benefit of being in the same application is that we can use direct code calls that do not rely on the network to succeed. In our proposal, a module provides with clients visible to other modules which act as the only direct entry points via code, defining the functional surface the module exposes.

src/
    Module1/
        ...
        Client/
            ClientV1.code
            ClientV1Mock.code

In terms of visibility, a module is allowed to import and use other modules' clients. And that's the only single piece of code they can import from the other modules. Ideally a client is defined as an interface, allowing to go with a direct code call implementation or an over-the-network implementation, in case it's needed (for instance, by an actual external application).

Clients are maintained by the team owning the module, which provide with a mocked version of it as well. This way, client modules have reliable test double that is up-to-date with the client input and output schemas.

Messaging communication

The client is covering direct code calls, when a module requests something to another module. With Messaging we cover the indirect communication, when something happens in a module that could be of interest for another module, in a pub-sub fashion.

src/
    Module1/
        ...
        Messaging/
            Publishing/
                SomethingHappenedHere.code
            SubscribedTo/
                SomethingHappenedElsewhere.code
    ModuleBus/
        MessageBus.code

The ModuleBus is the tool we provide for the modules to publish messages about their internal activity. Similarly to the clients, it defines a contract to publish messages, and it will take care of delivering it to the interested subscribers.

Modules will define which messages they publish and which messages from other modules they want to subscribe to. When a module publishes a message in the bus, it takes care to notify all the interested subscribers.

The highlight with this bus is that we can do in-memory messaging without the need to go through a message broker and the inherent complexity of async communication, while keeping the ability to be async when it makes sense. Furthermore, since from the modules' point of view there is a single contract, we can use the implementation of the ModuleBus to transition from in-memory to async in a transparent way as needed.

The persistence

Each module has its own isolated persistence system, only accessible by the module itself. As with everything there is a degree of convention involved. The isolation may consist in a totally separated database or a subset of prefixed tables in the same database.

We want to avoid shared data models that are polluted by data from unrelated domains. It's fine to have product_catalog_products and order_handling_products tables, even if both refer to "product". Product means something different in each context. The one from Order Handling should not care and should not be affected if we add a new column in the Product Catalog one.

Greenfield vs brownfield: migration strategies

So far we have described how to structure a monolith in a way it will look fantastic. This is relatively easy in a greenfield project, when building a system from scratch.

The reality is that most of the time we deal with already existing systems. Even more, our greenfield project will become a brownfield project in no time, where things are not as fantastic as we thought when we started.

Here are some strategies to deal with transitions from non-modularized to modularized monoliths. They are based on the premise that we want to be incremental, avoiding big bang releases where we replace big chunks of functionality with a fresh rewrite.

Migration events and responses

Because it's common to find big classes doing too many things, sometimes it's just not possible to replace them at once with a modularized version.

Instead, replace smaller parts of functionality with the modularized version, which will communicate back with the original functionality. Emit events or return ad-hoc responses so the original code can resume the logic not migrated yet. Even if that means breaking module visibility rules or leaking muddy monolith stuff into our pristine modules... as long as it is a temporary measure.

Shared persistence

To migrate to a modular monolith usually requires a time window when the logic in the new module shares the persistence with the older code. Because we need to support the working software, because we cannot just take over a table used in many places, or because many other reasons.

When moving some domain into a module, prepare a specific plan to deal with the database migration. The strategy here consists in not sticking to a dogmatic "modules do not share databases", but to be realistic while keeping a strong compromise to remove the persistence dependency once it's feasible.

Avoid on demand "modules"

As it has been stressed a few times already, identifying the right modules is not small task. Because sometimes we want to move fast, we may be tempted to create "modules" for everything, even when it does not match with the purpose and meaning of a module (hence the quotes). The result is an absurd number of modules, often with suspicious similarities in their name.

Do not create a "module" just for isolating something from the non-modular part of the monolith. The benefits of modularization come from how they aggregate and isolate related logic. We can improve the design of some part of our monolith within the same monolith.

Decisions are not forever

We may fail to define the right modules at first. Or we may succeed at it, but the problem space evolves and what once was right isn't anymore. It's probable that the current monolith will pollute our understanding, and we will -unconsciously or not- replicate the existing structure, which may not be ideal.

It is ok to discard or merge modules, or to shrink or expand them because we didn't put the boundaries in the right place. It's part of the learning process. Do not stick to what is there just because it's already there.

Concluding

We have covered a number of patterns to structure monolith applications, so they have solid organizational foundations:

Use modules as organizational units.
Limit the visibility a module offers to the others using contracts controlled by the module itself.
Provide a way for messaging communication among modules.
Do not share the persistence layer.

As pointed out, the value is in the purpose of the proposed patterns, not in the particular suggestions -which, in fact, are kinda naive on purpose. Still, we can mess up in each module concrete implementation. Once again let's stress how important is the domain discovery and setting the best boundaries we can.

If you have any other experience with modular monoliths -or any other feedback- it would be nice to hear about it in the comments. All good advice is welcome for the sake of monoliths around the world.

Credits

For the diagrams I've used Excalidraw, borrowing libraries from Mateusz Baran and Anumitha Apollo.

The cover picture is from the 1957 movie The Monolith Monsters which, according to Wikipedia, was the inspiration for the Tiberium mineral in the Comand & Conquer games O_o

Understanding Hexagonal Architecture

Carlos Gándara — Sun, 15 Oct 2023 15:38:46 +0000

Alistair Cockburn was kind enough to give his opinion on this post. Based on this, I have adjusted it a bit, highlighting the parts that changed.

The goal of the Hexagonal Architecture (aka ports and adapters, or HA in this post) pattern is, as originally formulated by its author Mr. Alistair Cockburn:

Allow an application to equally be driven by users, programs, automated test or batch scripts, and to be developed and tested in isolation from its eventual run-time devices and databases.

In a previous post we summarized the way it works as:

Hexagonal Architecture promotes the separation of an application internals from its interactions with the external world.

We have our application, represented as a hexagon. Outside the hexagon there are the external actors: users interacting with a graphical interface, messaging systems, databases, vendor APIs, etc.

The application defines the ways for it to interact with external actors. Each of these contracts is a port. Ports are expressed in application language, like parts of a use case. Adapters are the connections of the external actors with the application using a port. They are interchangeable ways of interacting with the application using different technologies.

Edited on 2024-08-02: The above paragraph was incorrectly stating that adapters are implementations of the ports, which is only half true. It's fixed now.

In this post we will dig deeper in each of the parts of the pattern and link them to code examples.

Driving and being driven

Before jumping into more definitions, let's first consider how our applications work from the perspective of the interactions with the external actors.

Some of these actors use our application (e.g. a call to our REST API). Other actors are used by our application instead (e.g. a database).

We call the former driver actors and the latter driven actors. How they interact with our application happens will determine the way we define the contracts the application sets for them.

Analogously, this distinction applies to ports, adapters, and sides of the application.

The ports

Ports are the contracts the application settles for the interaction with the external actors. Depending on the type of actor we are dealing with, driver of driven, this contract will look different.

Driver ports define how driver actors interact with the application. Therefore, they specify the input that must be provided in order to ask the application to perform the action the actor is interested in.

Driven ports define how the application will interact with the driven actor. Therefore, they specify what they want from the actor.

Since ports are defined by the application they are written in pure "application language", removing coupling to any detail of concrete technologies. Our application will not care about any technologies, because ports are isolating it from them.

Examples!

To create a user we need their email and password. The driver port for this use case defines this data as the contract the actor must adhere to in order to use the application. Whoever you are, if you want me to create a user, you must give me this.
Users are modeled in our application with the User entity. The driven port for storing users defines that there must be a way to store User entities.

The adapters

Actors interact with the application. Ports define how these interactions happen. Adapters fill the space between the actors and the application, enabling the conversation between them.

Adapters adapt (didn't see that coming) the details of different technologies into what the application has defined beforehand through ports. In the process, those details do not permeate inside our application, keeping it clean. If any response is expected by the actor, it's the adapter responsibility to produce it.

Following our previous examples, our port to create users specifies the application requires an email and a password. We may have:

For the "user interacting with a graphical interface" actor, an adapter for an HTTP REST API that takes the values from the HTTP request. It also returns the 202 response to the client.
For the "company CRM system" actor, an adapter for a message broker that gets the values from the message payload. The adapter takes care of sending the ACK of the message as well.
For some weird integration with an "old system" actor, an adapter reading the values from a CSV file this system is putting in our FTP server each night.

Wiring everything together: the Configurator

Edited on 2024-08-02: The first version of the post was not mentioning the Configurator.

On top of our application, the ports it defines, and the different adapters that connect with the ports, we need something that takes care of using the right elements in the right moment. This is what the pattern refers to as the Configurator.

Most of the times we use a framework when building software applications: Ruby on Rails, Spring, .NET, Django, etc. The framework usually takes care of the wiring of the different moving pieces, for instance by providing a service container. In an application built applying ports and adapters, that would be the Configurator.

It is something we may take for granted, but we must be aware that when not using a framework that provides this type of functionality, we must implement ourselves a mechanism to provide the hexagon with the right adapters for each request.

The benefits

With what have covered so far we have achieved significant benefits.

First, our application may be technology-agnostic. Its communication with the outside is defined via ports, with the adapters taking care of converting each technology quirks to what the port defines, which is what the application understands.

In practice, the application does not know about the database structure, that's for the database adapter to handle. Or if we get input data from an HTTP request or a CLI command, in JSON or protobuff, from Rabbit or from Kafka.

Second, with each port acting as entry point (or exit, depending on the port being driver or driven) we can use any number of different adapters. Therefore, our application can be extended just plugging in a new adapter. Pretty much as the strategy pattern.

And there is a third massive benefit: testing.

To test our application behavior without the need to have some real technology in place, we can -and certainly must- implement a test adapter that acts as a replacement.

For the driver ports, we don't need an actual message broker, or to mimic an HTTP request. A test adapter will just call the application sticking to the port contract.

For the driven ports, we don't need an actual database up and running. We can use faster and simpler in-memory implementations.

In fact, the port + test adapter combo allow to move on with the application implementation without worrying about with which technology the integrations will actually happen.

These decisions can be deferred until the last reasonable moment avoiding attaching ourselves to a certain technology too early, something that could influence further design for the wrong reason

For instance, we can use in memory persistence adapters without the need to pick a concrete database early on. We design our application without being influenced by the constraints the chosen database has, and once we have further developed our system we can pick the best database for it.

Naming ports and adapters

There is no recipe for naming in HA. Alistair Cockburn is a firm proponent of use cases, and his explanations of the pattern point to name ports and adapters in a use case oriented way. However, doing so or not does not change what the pattern solves. And patterns are about solving recurrent problems, not about doing it with a certain wording.

Alistair would propose to call ports following the naming pattern For[Doing][Something]. Examples for driver ports: ForPlacingOrders, ForConfiguringSettings, etc. For the driven side: ForStoringUsers, ForNotifyingAlerts, etc. Which is pretty cool, but sadly not something I've seen in the wild.

It's more common to find driver ports as PlaceOrder or ConfigureSettings and driven as UserRepository and AlertNotifier.

In the adapter side the trick is to reference the technology we are adapting. We can have CliCommandForPlacingOrders or MysqlDatabaseForStoringUsers. If not following Cockburn's naming pattern we could go with PlaceOrderApiController or RabbitMqAlertNotifier. There is also this pattern of adding the Using[Technology] suffix (credits to Frank de Jonge for this one), resulting in PlaceOrderUsingRestApi or UserRepositoryUsingPostgreSql.

Find the convention you are comfortable with and be consistent with it. Just mind that the most the naming express the architecture, the better.

What is "the application"?

Edited on 2024-08-02: edited to make it more concise.

One aspect not usually covered in the literature about HA is what the application or the hexagon actually is, which can be frustrating for newcomers.

The HA application is one element of the pattern. Ports are at its boundary. Therefore, adapters are outside of the application. HA is about isolating the application with the boundaries.

The application perceived by the external world is the whole system. Including the HA application, the adapters, the configurator, and any other code or files needed for it to run.

For a system to run we need some tooling that is outside the HA pattern. This is what is called a walking skeleton: the minimum code in our system that allows to run it. When using a framework, we can consider it our walking skeleton even when it comes with way more built-in features than the minimum needed to run. HA examples simplified for learning purposes may only need a small script as walking skeleton.

For what is worth, the concept of walking skeleton was coined by... Alistair Cockburn. The software industry indeed owns a lot to him and his work. For deeper reading on the concept I cannot less than recommend the book Growing Object-Oriented Software, Guided by Tests, which has a chapter dedicated to it.

Request lifecycle in Hexagonal Architecture

Now that we know all the moving parts we can foresee how systems built applying HA work.

Scenario: the company CRM has created a new client. The business policy when this happens is that we create a user for the client, send an email to notify her, and propagate the user was created so other systems can react to this action. Our application takes care of user creation and exposes a REST API, which is called by the CRM.

Pretty much a standard request for any system, no special complexity here.

The CRM is the driver external actor. Our application defines the CreateUser driver port, which has an adapter for the REST API: CreateUserUsingRestAPI. There is also a driven port UserRepository for user storage and another one UserCreatedNotifier. The adapters for them are UserRepositoryUsingPostgres, UserCreatedNotifierUsingEmail and UserCreatedNotifierUsingRabbitMQ.

Our application, which is built using our framework of choice, receives the request and detects it's arriving via HTTP. It wires together the adapters inside whatever service we have defined for handling this request and executes it.

When doing so, the application is not polluted with HTTP request payloads, content types, or headers. The adapter transforms all of that into what the port defines.

In the driver side, the application knows nothing about the database tables involved in persisting an user, or how the payload of the RabbitMQ messages should be. The ports define they will persist a user and will notify about it being created, and the adapters take care of transforming that application-defined instructions into what each technology requires.

Code examples

Before jumping into code, an aspect that cannot be emphasized enough: HA is just about ports and adapters.

It dictates nothing about how the application should be organized internally. There is no recipe for the number of layers our application should have, not even if it should have layers at all.

Command buses and handlers, DDD patterns, onions and upper case Clean Architectures, big balls of mud, etc. are all valid ways of implementing the internals of an application which applies Hexagonal Architecture. But there is no requirement or guideline dictated by the pattern on how it should be done.

Therefore, the following examples should be taken as ways of illustrating how ports and adapters work together. Not as the right way™️ to be hexagonal.

Now, the ports for our "create user" use case could look like:

Since the writing of the original post I've come to realize that this first code example is not accurate. Driver adapters use the application and this example proposes the application to use them. Although we would get the same benefits, the second code example is the one actually applying Hexagonal Architecture.

interface CreateUser {
    buildRequest(): CreateUser;
}

interface UserRepository {
    add(User user): void;
}

interface UserCreatedNotifier {
    notify(UserCreated event): void;
}

The adapters would be implementations for those interfaces using the different technologies suggested by their name.

Our application (in terms of HA) has a service to create the users, which gets as dependencies the ports involved in the use case:

class CreateUserHandler {
    private CreateUser createUser;
    private UserRepository userRepository; 
    private array<UserCreatedNotifier> notifiers;

    fn handle(): void
    {
        var request createUser.buildRequest();
        var user = new User(request.email(), request.password());
        userRepository.add(user);
        notifiers.each(x => x.notify(new UserCreated(user.email())));
    }
}

Our framework is configured to inject the right implementations -the adapters- for the current request and to call the handle method.

We can notice how using test adapters we could test the business logic of our handler without dependencies to actual infrastructure services: a TestCreateUser could provide baked test values, a InMemoryUserRepository would not need any underlying database system running, etc.

A different approach is when driver ports are not defined as interfaces, but as data structures the adapters must provide to the application.

Frameworks are good identifying the technologies used by driver actors, and we delegate to them invoking the right adapter. The adapter will pass the request contract to the application. This approach offers the same benefits as the driver-port-as-interface, delegating to the built-in tools of the framework the driver adapters' implementation:

# replaces the interface
class CreateUser {
    public readonly string email;
    public readonly string password;
}

# the adapter is a framework controller
class CreateUserController {

    private CreateUserHandler handler;

    fn createUser(HttpRequest request) {
        handler.handle(
            new CreateUser(
                request.payload.get('email'),
                request.payload.get('password')
            )
        );
    }
}

# the application no longer expects the port as dependency, but as a parameter
class CreateUserHandler {
    private UserRepository userRepository; 
    private array<UserCreatedNotifier> notifiers;

    fn handle(CreateUser request): void
    {
        var user = new User(request.email(), request.password());
        userRepository.add(user);
        notifiers.each(x => x.notify(new UserCreated(user.email())));
    }
}

When and when not

Patterns define well proved ways of solving common problems. The problem HA tackles is the difficulty to maintain, test, and evolve applications when they are too coupled to concrete technologies. But "too coupled" is a very contextual and subjective measure. What is valid for one team or project might not be for others.

Furthermore, context changes over time. What is a reasonable decision today may not be so tomorrow.

My personal take is that HA is actually so simple and the overload it implies so small, that it is the default approach I would use for any greenfield project. It just feels natural to abstract away the technical details using ports. Remember: HA is just ports and adapters, it does not necessarily imply DDD, buses, presenters, etc.

However, there are contextual factors that might justify not going with this pattern. The effort to move existing applications to HA may not be worth if the application is not expected to be extended and already has good test coverage. In a more social aspect of it, for teams of hardcore-framework developers (which is a legit standpoint) the switch to an architecture that pushes the framework away from the application core could cause a lot of friction, which might not compensate the expected benefits.

As always, no magic recipes. The advice would be to try it, explore it enough to understand what it gives and takes, and choose it when it fits.

Concluding

Hopefully this post has been useful to get to know the Hexagonal Architecture pattern. Maybe there is a degree of frustration because how high level it actually is. We devs (humans!) tend to look for guided solutions to apply without much thinking, and HA is quite lax in those terms. It's more a set of guidelines to avoid creepy scenarios than any guided way of building applications.

For less abstract guidelines there are other patterns that will put us more "on rails". HA just don't mind if you use these other patters or not. It only cares of protecting the boundaries of your application.

In following posts we will cover possible ways of designing the internals of our application while sticking to HA. With a bit of luck they won't take as long as this one.

Credits

For the diagrams I've used Excalidraw, borrowing libraries from Youri Tjang, Drwn.io, David Luzar and Ana Clara Cavalcante

The cover picture is from Penny Richards, distributed under the Creative Commons license. It can be found here.

What is (not) Hexagonal Architecture

Carlos Gándara — Tue, 01 Nov 2022 10:16:44 +0000

Hexagonal Architecture (HA) is one of those "buzzwords" we hear a lot in the development world. This post tries to explain a bit what is it about and, more important, what it is not. Don't expect a thorough tour over the pattern here, but a short introduction and a reflection over what floats around it.

Mmmm... so what is Hexagonal Architecture?

It is an architectural pattern coined by Dr. Alistair Cockburn in 2005. It promotes the separation of an application internals from its interactions with the external world.

And what is not?

Many things. Probably they will appear sooner or later in this fictional conversation. In fact, as the author, I'm pretty sure they will appear :D

For now, I can tell you it's a term that has been corrupted as many others in the industry, like Devops, Microservices,or Agile. Although the term Hexagonal Architecture has been less bastardized than these other examples, there is plenty of fantasy around it.

How the pattern works?

We have our application, represented as an hexagon. Outside the hexagon there are the external actors: users interacting with a graphical interface, messaging systems, databases, vendor APIs, etc.

Edited on 2024-08-02: The following paragraph was incorrectly stating that adapters are implementations of the ports, which is only half true. It has been fixed. For more details, take a look here.

The application defines the ways for it to interact with external actors. Each of these contracts is a port. Ports are expressed in application language, like parts of a use case. Adapters are the connections of the external actors with the application using a port. They are interchangeable ways of interacting with the application using different technologies.

Where is the value?

HA facilitates easier to understand, easier to test, and easier to extend applications.

The isolation of the application from the outside world using ports means the application is not "polluted" with the details of external actors, reducing the cognitive load needed to understand the application logic.

The interchangeability of the adapters allows to have a test adapter for each port which can be used as replacement of the real actor, instead of forcing us to spin up the real stuff to test our application. Specially handy when the actor is a human being.

The combo of a port defining the interaction contract plus its multiple possible adapters allows to plug-in new technologies without having to modify the application. A new adapter for the new technology will do the trick.

All those three benefits are potential, though. HA is not a recipe to guarantee we don't produce a mess. But for sure the chances to do so are drastically reduced.

Why an hexagon?

The hexagon has no special meaning. It was just convenient when Cockburn came up with the pattern: easy to draw, easy to showcase the pattern, and not already taken for another recognizable diagram out there. Actually, after some time he realized a better name would be ports and adapters, but by then the hexagonal was too rooted in the community.

Should I use Hexagonal Architecture in all my applications?

There are very few universal things in software development, and no pattern is any of them. HA has its usages and they are wide, but it's not a good solution for every single case. The context of each application will determine if going hexagonal is the right approach. The benefits it provides can be irrelevant in some cases, not only for the nature of the application but also for its contextual circumstances: fixed lifetimes, tooling already in place, social aspects of the team, etc.

The pattern shines the more in the situations where many entry points for the same use case exist, which fits with most of the modern enterprise applications. Even when there are not those many entry points, the ability to use test adapters can be beneficial enough to justify applying it.

How should I arrange my code to follow Hexagonal Architecture?

Arrange it in any way you want, as long as the interactions with the external actors are done through an API defined by the application (a port).

But is not this a Clean Architecture? Should not HA tell me where to put my stuff?

Nope. HA indeed serves as an excellent base for clean architectures (note the small letters), and indeed is the base for the Clean Architecture (note the capital letters), understood as the "brand" commercialized by Robert C. Martin. But they are not the same, since Clean Architecture is an opinionated implementation of HA. The same applies for the Onion Architecture, the other popular superset of HA.

Really? And all this stuff about layers and command buses the people that does Hexagonal Architecture uses?

That's one popular way of implementing what is inside (and outside!) the hexagon, but the pattern does not enforce or forbid any of it. It just says to put a port in the application boundary when it has to interact with some external actor.

And what about Domain-Driven Design?

It's another misconception that DDD equals HA, or that one cannot exist without the other. Certainly HA is an excellent support for some of the DDD practices and patterns, but you can perfectly make use of any of them separately. Same for CQRS and Event Sourcing, in case you were about to ask about them.

I'm kinda disappointed...

Be not. Hexagonal Architecture is a powerful pattern, don't be fooled by its simplicity. As many other brilliant things, it's simple in the surface but has a fascinating depth.

I really was expecting something more concrete I could apply

That's normal. We developers like recipes we can directly use to solve our problems. It's natural that we try to narrow what gives us too much freedom into something tangible we can execute "on rails". We want solutions and we want them fast. Since HA is really lax in this sense, we have convinced ourselves that it is another different thing which guides us more strictly.

Worth to say that all these things that are usually mixed up with Hexagonal Architecture are not less valuable because they are not exactly Hexagonal Architecture.

What is the point of this post, then?

I was hoping that clarifying some of the myths around HA could help to understand that the complexity usually associated to it is actually part of other patterns and techniques that may or may not rely on HA.

We should be aware that we should not discard the benefits HA provides because we are forced to deal with this complexity.

Interesting. I'm intrigued now about this pure HA vs adorned HA

Curious way of putting it. Anyway, in following posts I will try to dig more in both.

Looking forward to it!

Kitchen clocks, health and productivity: the Pomodoro Technique

Carlos Gándara — Sun, 30 Jan 2022 19:27:28 +0000

Cover image taken from https://bgfons.com

The Pomodoro Technique is a time management technique. Using it when developing may positively impact not only our productivity, but also our health.

Here we will cover its basics and some tips on how to use it in the context of software development.

The Pomodoro Technique

The technique has a number of steps to organize our activities, any of them. For the whole day. It focuses on maximizing the use of our mind without the burden of a complicated framework. It is fairly simple. Not easy at all, but simple.

I encourage you to fully read it. Then, as it should be with any tool, embrace it all or skip what does not work for you knowing why every piece is there and the consequences of dropping them.

In this post the focus will be in the execution part as it is what I think has the most impact when coding.

Using Pomodoros

Premises:

Distractions are a productivity killer.
Our brain works way better if we give it some rest from time to time.

These are not empty claims, they are backed scientifically [1][2].

The Pomodoro Technique proposes:

Working in time-boxed periods during which we should keep the focus in what we are doing, avoiding distractions.
Taking small breaks between each of these periods giving some room to our brain to process whatever we are doing.

Going more into details, the "canonical" Pomodoro execution is:

Work in periods of 25 minutes, which is called a Pomodoro.
After each Pomodoro, take a 5 minute break.
After the fourth Pomodoro in a row, take a longer break of 10-20 minutes.
Start over.

Usually the summaries of the technique stop here, which in my opinion misses the point. Actually, the time-frames are not that important and can be adjusted to fit the activity or individual taste. Just "doing Pomodoros" brings marginal results compared to consciously take into account the premises mentioned before.

What we must pay attention to is:

During a Pomodoro, focus 100% in the task at hand, discarding distractions.
During a break don't do anything demanding for your brain.

These two points deserve way more attention that the concrete amounts of time per Pomodoro.

The distractions

A distraction means we will try to do two things at the same time and losing the focus because of the context switching.

The human brain is bad at multitasking. Actually, it is not able to do so. Instead it fakes it switching between tasks very fast, not doing them in parallel.

In the other hand, if we are in the zone and we get distracted, it will take us more than 20 minutes to get to the previous level of concentration. Yes, this means our days are a dramatic waste of energy.

Half of the The Pomodoro Technique is about removing distractions. Both the external ones that come to us (chat messages, incoming email pop-ups, somebody jumping in with a question,...) and the internal ones that we do to ourselves (like thinking on what to have for dinner while doing a refactor).

The number of internal distractions we inadvertently do to ourselves is insane. The technique suggests, pen and paper nearby, to take a note every time we found we are being self-distracted. A simple scratch will suffice, it is about the amount not about the details. Once we have this graphic visualization of them it is easier to start to avoid doing so many.

About external distractions, the strategy is to delay them as much as possible. It is very unlikely something cannot wait a max of 25 minutes. Most probably it can wait hours or even days. Every time something "urgent" appears, learn to kindly reply you will check it in some minutes, or ask how long it could wait. Take a note about what you committed to tackle later and group these tasks together in dedicated Pomodoros.

The result of those two simple moves are more productive Pomodoros: distractions and context switching are reduced and the external requests have our full dedication as well.

The breaks

Breaks are for giving some rest to our brain. Not to answer emails, doomscrolling over social media or review the last messages in the company chat (including the channel #puppies).

During a break do something not mentally demanding. Go make a tea, stare through a window, walk a bit. Do nothing at all. Allow your brain to organize itself after these past 25 minutes on full focus (this is called assimilation).

It is refreshing, we will be less tired, and getting back into the zone for the next Pomodoro will happen effortlessly.

If otherwise we spend the break time doing something our brain pays attention to, the result will be a harder and longer time to be concentrated again and an increasing tiresomeness.

For the longer break every four Pomodoros consider even going for short walk. If we are able to disconnect from what we were doing it will still be easy to catch up and we will be increasing the odds of an aha moment because of the time we give our brain to accommodate and assimilate.

Pomodoros in the developer life

Coding is a intellectual activity, demanding to our brain and that pushes to a sedentary lifestyle. Pomodoros may help with all of that. Its structure can be used in our advantage to mitigate many of the problems associated with the life as a developer.

We are used to deal with all sorts of instant notifications. Re-evaluate the need of getting a pop-up alert every time you get an email or a new chat message. Mute all channels you can. Those are distractions that will impact your focus during a Pomodoro. Establish a routine to read them in batches and delay everything that can be delayed.

Coding is usually done seating, resulting in long periods of time in the same position. Use the breaks to get up. Walk a bit. Do some stretching.

Most likely we are staring to screens when coding. Continuously focusing at the same distance is pernicious for the eyes as well. During breaks we can apply the 20-20-220 rule looking through a window to something far away to force our eyes to refocus.

Finally, working from home is quite a thing nowadays. Doing otherwise ungrateful housework tasks are good candidates for the breaks. They are done by muscle memory and do not require mental effort, giving the needed space to our brain to rearrange. This is a win-win: convenient Pomodoro breaks and the dishwasher emptied.

Concluding

We did a shallow review of what the Pomodoro technique is, putting the view in what I think is the most relevant, and often forgotten, aspect of it. Again, I recommend fully reading the manual to have a better view of the whats and the whys.

Applying it correctly is not easy and generates some friction at the beginning, because it impacts in so many points of our usual day. I've being using it for years and now and then I fail to stick to the technique. Those days usually end up in worse mood than they should, because the waste of productivity becomes patent.

To conclude, some well deserved trivia:

The Pomodoro Technique was created by Francesco Cirillo in 1980.
Pomodoro is the Italian word for tomato.
The name comes from these kitchen clocks used to track the time when cooking stuff. Cirillo used them to time-box his Pomodoros.
Here is official website.

Give it a try and don't hesitate to comment with your experience.

Given-When-Then tests

Carlos Gándara — Mon, 27 Dec 2021 20:29:53 +0000

Consider this test written in the "traditional" format in a test framework of the xUnit family:

/** @test */
public function calculatesOrderCost(): void
{
    $itemA = Item::withPrice(20);
    $itemB = Item::withPrice(60);
    $shippingCost = ShippingCost::asPercentage(10);

    $order = new Order();
    $order->addItems($itemA, $itemB);

    $order->applyShippingCost($shippingCost);

    self::assertEquals(88, $order->totalCost());
}

In this post we will analyze the benefits of using the GWT format instead:

/** @test */
public function calculatesOrderCost(): void
{
    $this->givenAnItemWithPrice(20);
    $this->andAnItemWithPrice(60);
    $this->andAShippingCostOfPercent(10);

    $this->whenOrderIsCreated();

    $this->thenTotalOrderCostIs(88);
}

What is GWT

Basically what happened is that we moved the different parts of the test to dedicated methods of any of the GWT types:

The Given, meaning the state of the system required to execute the code under test.
The When, meaning the execution of the code under test.
The Then, meaning what is the expected output after executing the code.

Since each of these blocks is very likely to have more than one step, each of the blocks can include And methods as shown in the example.

GWT comes from BDD (Behavior Driven Development), an approach to testing coined by Dan North with a focus on behaviour, which in turn has lead to the creation of dedicated test frameworks (such as Cucumber, Behat or SpecFlow). In BDD, using GWT is the basis to write the test scenarios, whilst in xUnit frameworks is not that common to see this format and certainly more cumbersome to do. They're frameworks were not written with GWT in mind. However, using GWT there provides noticeable benefits as well.

The benefits

What we achieve with the GWT format is:

1. Better readability

Making the tests resemble human readable descriptions of what our application does moves them towards the desirable state where our tests are "living documentation". They reflect what the system does and they will change along with the system when required, making them always up to date documentation.

2. Reduce the cognitive load

To get what's going on in the test we can read each step of it without the visual noise produced for the code required to implement it. The example is pretty naive for simplicity purposes, but we can easily imagine Item or Order would require a lot more parameters to be instantiated while we only care about the ones involving the cost in this case.

3. Verify the behavior of the system under test instead of its implementation

Testing the implementation instead of behavior is not desirable. It makes our tests and production code less prepared for refactoring and change. Because in GWT we describe what the system does, the test is less prone to fall in the trap of being coupled with the implementation.

It is important to note that GWT does not guarantee any of the above benefits, neither it means they cannot be achieved using another approach or other techniques. It just makes them easier to accomplish.

Trade-offs and considerations

There are few things in software development that have no trade-off included, and BDD and GWT tests are not an exception.

BDD frameworks rely on Gherkin language to define the steps of a test in a separate feature file, and using regular expressions find the matching method implementation. For instance Given '1' items with price '80' euro* will be matched with a method givenItemsWithPrice(int $amount, int $price). xUnit frameworks are not prepared for this type of pattern matching and the methods in GWT tests do not read as good as the pure BDD counterparts. In our xUnit tests we will have just the method implementation, not the more readable feature file.

Another aspect to consider is that when using GWT everything is encapsulated in separate methods and tests tend to store stuff in class properties to use them later on. This means tests may have more properties and state than what we may be used to, with later methods relying on properties set by prior ones. Sometimes this may produce null pointer exceptions and tests that are harder to follow:

/** @test **/
public function shipingToAddress(): void
{
    $this->givenAnAddress(); 
    $this->whenOrderIsShipped();
    $this->thenPackageIsSent();
}

private function givenAnAddress(): void
{
    // We need an address property
    $this->address = new Address('sesame street');
}

private function whenOrderIsShipped(): void
{
    $shippingService = new ShippingService();
    // This method relies on an address previously set, producing a confusing error when it is not
    $shippingService->shipTo($this->address);
}

Finally, GWT tests work better when we are testing code involving business rules. When testing classes more related to infrastructure, utilities, data manipulation,... GWT does not work that well and result in cumbersome tests that feel forced:

/** @test **/
public function sanitizeTextGWT(): void
{
    $this->givenATextWithAccents(); 
    $this->whenSanitizingTheText();
    $this->thenAccentsAreRemoved();
}

/** @test **/
public function sanitizeText(): void
{
    // Maybe GWT does not provide much value compared to this
    self::assertEquals('aa', Sanitizer::sanitize('áà'));
}

As with every tool, the point is to use the it to solve our problems, not to bend the problems to force them into it.

Tips and tricks

Here are some techniques and soft rules that I found give good results when using the GWT approach in xUnit tests.

Do not use And

Using and at the beginning of a method reads pretty well when we write our first tests, but could lead to weird situations when a test needs the steps starting with and but none of the ones starting with Given, When or Then:

/** @test */
public function carReactsToAdverseWeather(): void
{
    $this->givenThereIsMist(); // In this test rain is relevant
    $this->andItIsRaining(); // So this reads nice
    $this->whenWeatherIsScanned();
    $this->thenMistLightsAreTurnOn();
    $this->andDriveAssitanceOnWetRoadIsTurnOn();
}

/** @test */
public function carReactsToNotSoAdverseWeather(): void
{
    $this->andItIsRaining(); // We don't care about the mist ant it reads weird 
    $this->whenWeatherIsScanned();
    $this->andDriveAssitanceOnWetRoadIsTurnOn(); // Same here
}

Instead, avoid and prefix and use always given, when or then. It won't read as good as with and, but the benefit is greater than the loss.

/** @test */
public function carReactsToAdverseWeather(): void
{
    $this->givenThereIsMist();
    $this->givenItIsRaining();
    $this->whenWeatherIsScanned();
    $this->thenMistLightsAreTurnOn();
    $this->thenDriveAssitanceOnWetRoadIsTurnOn();
}

Test error cases catching exceptions into a property

xUnit frameworks provide a fancy way of dealing with exceptions when throwing them is the expected behavior. However, it does not fit well in GWT because it would break the test structure or produce "technical sentences" in a otherwise human-readable test. A way of avoiding that is to use a try-catch inside the When method saving the exception in a property for a later, more meaningful assertion:

/** @test **/
public function shipingToAddress(): void
{
    $this->givenAnAddress();
    $this->givenClientHasNoFunds();
    $this->whenOrderIsShipped();
    $this->thenOrderFailedDuetoNoPayment();
}

private function whenOrderIsShipped(): void
{
    try {
        $this->shippingService->ship();
    } catch (Exception $ex) {
        $this->exceptionWhenShippingOrder = $ex;
    }
}

private function thenOrderFailedDuetoNoPayment(): void
{
    self::assertInstanceOf(NoPaymentException::class, $this->exceptionWhenShippingOrder)
}

Reduce the number of properties with return values and method parameters

The body of a GWT is composed of a bunch of methods, one after the other. If we do just that, we will be forced to use lots of properties to hold the values generated in by Given methods to use them in the following steps. This may hurt the readability of tests and makes them harder to follow because we cannot notice it unless we go into each of the methods, it is not visible explicitly in the test body.

/** @test */
public function calculatesOrderCost(): void
{
    $this->givenAnItemWithPrice(20); // Requires storing a property for the item
    $this->givenAnItemWithPrice(60); // Another property
    $this->andAShippingCostOfPercent(10); // Another property

    $this->whenOrderIsCreated(); // Will use the previously set properties

    $this->thenTotalOrderCostIs(88);
}

But our methods can return stuff and accept parameters, and we can avoid overuse of properties playing with that (which is actually an advantage compared to BDD frameworks).

/** @test */
public function calculatesOrderCost(): void
{
    $oneItem = $this->givenAnItemWithPrice(20);
    $anotherItem = $this->givenAnItemWithPrice(60);
    $shippingCost = $this->andAShippingCostOfPercent(10);

    $this->whenOrderIsCreated($shippingCost, $oneItem, $anotherItem);

    $this->thenTotalOrderCostIs(88);
}

Conclusion

Writing tests in GWT form could result in more valuable tests, because it makes easier to describe the behavior of the system and it kinda enforce us to write our tests the right way ™️. Give it a try to check how well it fits with you code style, always taking into account that, as like any other tool, it comes with a number of benefits but also trade-offs.

Hopefully this post has spark some curiosity. Let me know in the comments :)

PS: because I could not figure out something adequate as cover image, I've just randomly used a pic of one of the most mesmerizing animals out there, a Red Panda.

Refactoring with baby steps

Carlos Gándara — Sun, 09 May 2021 15:37:42 +0000

In a previous post we introduced the blessings Value Objects grant to our code. However, if we are not using them since the beginning we might ponder if it is worth messing up our whole codebase to introduce VOs. I can tell you it is totally worth it.

However, it is not that simple to introduce VOs (or any other change for that matter) into an existing codebase. In this post, we will see how to safely do it applying refactor techniques in small steps.

All the code changes presented here, and more, are published in this Github repository.

Precondition: test coverage

First things first, no matter the kind of change we want to introduce we need to be sure that we are not breaking our current code. The way of assuring it is through tests. Depending on the test coverage we have and its quality, on average we can face one of these three scenarios:

A) We have decent tests that cover the behavior of the code we want to change.
B) We have tests but they are coupled to the implementation of the code.
C) There are no tests at all.

If we are in scenario C, the first step to take is writing the tests. Ideally, the ones that put us in scenario A.

If we already have tests we can be in scenario A, which is a cozy environment for refactor and the code can be changed with little to no changes in tests. If we are in scenario B we will probably need a good deal of changes in the tests.

Introducing Value Objects can be considered a soft change in terms of impact on the component being modified. Value Objects apply when passing data around or operating with it. They don't substitute complex dependencies (e.g. accessing the database). We should expect a reduced amount of changes in the tests when introducing them, but that's highly dependant on the codebase we are dealing with.

The process

Refactoring in baby steps means we take small and safe steps, one at a time. Like babies do.

We will start in a green state (the tests are passing), and we will introduce one single change and run the tests. This change will be the smallest possible we can figure out that moves us in the direction of what we want to achieve. Sometimes they will mean a "step back" in terms of code quality, like introducing duplication, optional parameters, weird method naming, etc. But that's ok because those are temporal intermediate states until we reach our refactor purpose.

After any change, if the tests are still green we happily proceed to introduce the next change. If the tests become red, we will know exactly which change caused it. Either we undo it and start over from the last green state, which will be only one change away, or we identify the reason for the error and correct it.

Most of the time the smallest possible change is not bigger than a single line. Identifying the reason for a red in the tests becomes quite easy because the amount of code directly affected is small. When we modify larger chunks of code it is more likely we would not know where we introduced an error and we would invest more time, on average, to figure it out.

Should I apply baby steps always?

No. But...

During the process described here, some of the steps may look ridiculous and we could think we could take a group of them and apply them together straight away. That's fine as long as we do it consciously. That we know we are tackling a number of smaller steps at once, and we have the mental discipline to roll back the changes and start over, one small step at a time if it is needed. We cannot get to this position unless we practice enough applying baby steps to the point we internalize it.

We will notice we take a lot of steps to reach our refactor goal and we don't spend a lot of time fixing possible errors. Because the time spent fixing wrong decisions is minimal (because the decisions are minimal as well) we will be advancing at a continuous pace. The process is overall faster and safer than taking a big chunk of changes at once and having to think about what we did wrong when it does not work.

With practice comes experience, and with experience comes the confidence to take bigger steps. But we should always have the baby steps tool ready if things get messy.

The code we will refactor

Now we will apply refactoring with baby steps in a simple code example but juicy enough to showcase the process, set in the context of the aforementioned Value Objects post: a Jira-like software managing Story Points as primitive int values.

The method we will refactor is:

class SprintReport {
    public function __construct(
        private int $completedStoryPoints,
    ){}

    public function addCompletedStoryPoints(int $amount): void
    {
        if ($amount < 0) {
            throw new InvalidArgumentException('SP cannot be less than 0');
        }

        $this->completedStoryPoints += $amount;
    }
}

Diligent as we are, it is covered by the following (truncated) tests :

final class SprintReportTest extends TestCase
{
    /** @test */
    public function completedPointsDoNotChangeWhenAddingZeroStoryPoints(): void { ... }

    /** @test */
    public function failsWhenAddingLessThanZeroStoryPoints(): void { ... }

    /** @test */
    public function registersStoryPointsWhenAddingAValidAmountToAnEmptyReport(): void { ... }

    /** @test */
    public function addsUpStoryPointsWhenAddingToANonEmptyReport(): void { ... }
}

For reference, this is how a test actually looks like:

final class SprintReportTest extends TestCase
{
    private SprintReport $sprintReport;

    protected function setUp(): void
    {
        parent::setUp();
        $this->sprintReport = new SprintReport(0);
    }

    /** @test */
    public function addsUpStoryPointsWhenAddingToANonEmptyReport(): void
    {
        $this->sprintReport->addCompletedStoryPoints(3);
        $this->sprintReport->addCompletedStoryPoints(5);

        $expected = new SprintReport(8);
        self::assertEquals($expected, $this->sprintReport);
    }
}

And our StoryPoint Value Object:

class StoryPoint
{
    public function __construct(private int $value) { }

    public function value(): int
    {
        return $this->value;
    }
}

The first refactor

Now that the ground is settled, we start to refactor. We will refer to the current implementation as the "old method" and the one we are introducing as the "new method".

Step 1: Adding an empty method

A new empty method that accepts our StoryPoint VO as parameter. Nobody is using it yet so it should not break anything. We run the tests and indeed they are still green.

Step 2: Instantiate a StoryPoint using the int value

In the old method, we instantiate a StoryPoint from the int parameter. Tests are green, life is simple.

These two first steps may seem stupid. Well, we don't think (at least I hope so) babies are stupid because they start walking with small steps that are extremely conservative compared to their usual crawling. They are afraid of failing and so we are. They have pretty much less to lose than us being cautious, and still they are. There is something to learn here.

Indeed, with time and experience, we will happily be applying these two steps at once without hesitation.

Step 3: Duplicate the guard clause in the new method

This one is more interesting. We duplicate the clause guard checking the value of the story point is valid in our new method. Because the value is encapsulated in the VO, we check it using the getter we have for it.This is not a good approach from a VO point of view, the VO should be self-validated and the fact we have an instance means it is valid. In other words, the validation should happen inside the VO. But our focus right now is to get rid of the old method using primitives and replace it with usages of our VO. After that, we will be in a better position to apply a second refactor and make our VO self validated.

The tests are still green.

Step 4: Call the new method after the guard clause

Now that we actually call the code we duplicated in the previous step and the tests are green, we know that our duplicated guard works as expected when the input is valid. However, we don't know if we did a mistake when checking invalid input since the guard in the old method will fail and prevent our new method from being executed. But we are in an optimal scenario to verify our new guard validates correctly.

Step 5: Delete the old guard clause

Actually, the recommended approach here would be to comment out the old guard, run the test, check they are green, and actually remove the old guard clause. Commenting code is safer than cutting text or rely on the undo operation of our editor. When we comment we always "move forward" and the code is "persisted" instead of going backward with undo or put our hopes in the hands of the volatility of the clipboard.

When we totally delete the old guard clause and verify the tests are green, we can confirm our new guard clause correctly validates both valid and invalid input.

Step 6: Duplicate and comment out the increase of story points

Replacing this part of the old method is tricky: we cannot keep the old one and the new one at the same time because it is an operation that modifies the state of our SprintReport and keeping both would do the modification twice. We duplicate it adapted to the usage of StoryPoint but commented out. Doing so we can easily switch between both implementations to verify tests are green and go back to the old one in case they are not.

With the commented new code tests are still green.

Step 7: Uncomment the new increase, delete the old one

Doing the switch between implementations commenting and uncommenting each of them allows us to run the tests for each with the ability to switch back if we broke something in our new code. Once we verify we did not, we can delete the old implementation for good.

Step 8: Update the tests to use the new method

At this point, we have a new method using the VO as parameter and an old method that only instantiates the VO from the int parameter and calls the new method. We can now replace all of the usages of the old method with the new one. The spectrum of this change will affect the tests and the whole application.

Depending on how many times the old method is used this change could imply a lot of updates in different parts of the application and may not be a good mass update to tackle at this point. Maybe it is better to iteratively update its remaining usages when going through the code using it while we work on other tasks. We can make this explicit for future devs renaming the method to something that evidences it is recommended to use the new method or flagging it as deprecated.

In any case, the following steps are not especially sexy: automated renames using the IDE and "search and replace" usages of the old method. We will skip them here, but you can check them in the repository.

The second refactor

Although we have a method expecting a StoryPoint that substitutes the old one dealing with primitives, we still have room for improvement in other areas:

The SprintReport still uses int for tracking the Story Points.
The validation of a correct amount of Story Points happens outside the VO.
The addition of Story Points in a report uses the internal value of the VO, instead of doing the addition using a add() method exposed by the StoryPoint.

Covering all this stuff would take too much for this already too long post, so we will focus on the first one showcasing another technique to apply baby steps when refactoring: adding optional parameters with a default value.

Step 1: Add a new optional StoryPoint parameter to the constructor

The new parameter defaults to null, hence any previous usage of the constructor won't fail and tests are green. Doing so we allow to introduce usages of the new constructor parameter and adapt the class to use it while not breaking any existing code.

Step 2: Conditionally set the initial story points from the VO parameter when provided

Now our constructor sets the initial Story Points from the optional parameter when it is provided. Nobody does so yet and the tests are green. At this point, we are in the position of iteratively provide the optional parameter while keeping our SprintReport functional.

Step 3: Update the tests to provide the optional parameter

Since this is an educational post our class is quite simple and only used in the tests, so we just need to update them. However, in reality, there would be more usages of SprintReport, and adapting all of them might be a huge effort.

An alternative to going over all SprintReport constructor usages is to add a new static factory method to it, allowing to incrementally update our codebase to use the VO typed parameter while keeping compatibility with the int one:

class SprintReport
{
    public static function withCompleteStoryPoints(StoryPoint $completed): self
    {
        return new self($completed->value(), $completed);
    }
}

Since here we only have the tests using it, we update them right away.

Step 4: Duplicate and comment the assignment of completed Story Points

With this step we will allow, by switching between the conditional assignment and this new one, to verify all the usages of SprintReport constructor are updated. When commenting the conditional block and using the new one, any test covering a usage that is not providing the VO parameter will fail.

Step 5: Delete the conditional block from constructor

Once we are sure all the constructor usages provide the VO parameter, we can delete the conditional assignment.

At this point we can perform automated refactors with our IDE, changing the constructor signature to accept only the VO parameter and completing our change to remove the usage of Story Points as integers.

More refactors

As mentioned before, there are several other changes we could do in SprintReport and in StoryPoint to improve our implementation and usage of Value Objects for this case.

That would be too much to describe here, but you can check in the repository the next steps to make the most out of the encapsulation Value Object pattern provides. In small and safe steps :D

Final words

A TL;DR version of this post could be:

Always have tests in place.
Apply the smaller change possible, run the tests. They will be probably green because the change was minimal.
If tests are not green, fixing or going back to the previous step is trivial because the change was minimal.
We save time refactoring in baby steps.
Maybe we don't notice we save time just because we don't spend time figuring out what we did wrong when introducing a non-trivial change.
With practice and experience, we will be able to take bigger steps. But we should do it consciously and be able to fall back to baby steps if things get messy.

As with any stuff, it will take some time to get used to this type of approach to refactoring. As with the good stuff, once you are into it it is difficult to turn back.

For a more profound and consistent read about refactoring and object-oriented programming in general, I can recommend you the book 99 bottles of OOP by Sandy Metz, Katrina Owen, and TJ Stankus. I recommend it even if you have no interest in refactoring with baby steps. It may be one of the best books about writing OOP out there.

And that's all for today. As always, feedback is much appreciated. See you!

PS: I talk about Story Points here because it is a handy example, but I discourage using them. And so do the people who invented them. You have been warned.

PS2: If anyone knows any decent software to generate visually appealing diff images, please let me know. Going screenshot as I did here is hell.

A mockumentary about Value Objects

Carlos Gándara — Tue, 12 Jan 2021 21:15:51 +0000

Some weeks ago, this happened:

It is a screenshot from the actual changelog of the Jira app in the App Store. Two thoughts outstand from the several that arose when I saw it for the first time:

In which scenario this may be considered worthy to be highlighted.
What a good case it is for explaining the power of Value Objects (VOs).

Let's take a number of assumptions about how Jira is implemented in order to illustrate what the Value Objects pattern is and why it is one of the most powerful patterns in object-oriented programming. Needless to say, the example is 100% made up and not based on the actual Jira code.

Pattern definition

The definition of Value Object according to wikipedia is

A small object that represents a simple entity whose equality is not based on identity

I would say they are not necessarily small, although it is legit to claim they are usually small. Furthermore, there are other non-mandatory but highly desirable characteristics of Value Objects:

They are immutable.
They attract behavior related to the concept they represent.

Leveraging encapsulation and semantics

Coming back to our new outstanding Jira feature, let's assume the ability to have decimal story points is that important because a) it was not possible before and b) there is a fair amount of work behind making it possible.

Let's assume as well, and it looks like a fair assumption, that Jira has a massive codebase. It is a huge application and it has been around for a while. Probably Story Points are all around the place since they are a relevant piece of the average adoption of Scrum, a field in which Jira kind of excels.

Now consider the following code snippets from a possible implementation of some of the concepts Jira handles (in PHP, just in case it is not clear enough the not-real nature of the code exposed):

class Task {
    private string $id;
    private string $title;
    private int $storyPoints;

    public function estimation(): int {}
}

class Sprint {
    private TaskList $tasks;
    private int $totalStoryPoints;

    public function estimation(): int {}
    public function addTask(Task $task): void {}
}

class SprintReport {
    private int $completedStoryPoints;

    public function addCompletedStoryPoints($date, int $amount): void {}
}

All the references to int values are actually references to Story Points. As the code is now, allowing decimals for them is far from trivial: we have seven different appearances to change only in this small bit of code. Imagine the whole codebase or even the implementation of the methods outlined here.

Now, if we consider the following Value Object to model the concept of Story Point:

class StoryPoint {
    public function __construct(private int $value) {}

    public function value(): int {
        return $this->value;
    }
}

and how the code would look like using it:

class Task {
    private string $id;
    private string $title;
    private StoryPoint $estimation;

    public function estimation(): StoryPoint {}
}

class Sprint {
    private TaskList $tasks;
    private StoryPoint $totalStoryPoints;

    public function estimation(): StoryPoint {}
    public function addTask(Task $task): void {}
}

class SprintReport {
    private StoryPoint $completedStoryPoints;

    public function addCompletedStoryPoints($date, StoryPoint $amount): void {}
}

The change from integer to float, allowing decimals, implies only two changes: the two int references in the StoryPoint Value Object. And probably whatever mapping you are doing in your persistence system to translate a Story Point to a database column supporting decimals, something required whatsoever.

Confronting our VO with the pattern definition it hardly could be smaller than that, although size is not a key aspect.

It is identified by its value, meaning we don't care about having one instance of it or another as long as they hold the same value:

$aStoryPointVO = new StoryPoint(2);
$anotherStoryPointVO = new StoryPoint(2);

//using one VO or the other is indifferent
//and would result in an equivalent Task
$aTask = new Task('task-id', 'Task title', $aStoryPointVO);

Our VO sticks to the definition and that's good. In the end... well, it is a VO. Out of the box, Value Objects provide encapsulation, greatly reducing the number of places to modify when introducing a change in the concept they represent, and semantics. The other two aspects we mentioned before, immutability and attracting behavior, are not "built-in" and they depend on our diligence.

Attracting behavior

Attracting behavior is something that comes naturally and bolsters the encapsulation and meaningfulness of the Value Object. Immutability is quite related to it as well. We will use the method addCompletedStoryPoints in our SprintReport example to illustrate both. Consider this not desirable way of implementing it:

class SprintReport {
    private StoryPoint $completedStoryPoints;

    //Don't do this
    public function addCompletedStoryPoints($date, StoryPoint $amount) {
        $previousValue = $this->completedStoryPoints->value();
        $addedValue = $amount->value();
        $this->completedStoryPoints = new StoryPoint($previousValue + $addedValue);
    }
}

With this operation we are breaking the encapsulation provided by the Value Object: the client code (the method) knows that the internal representation of the value of StoryPoint is an integer and we fall into the same trap as before, because a change in this internal value will lead to updates on several parts of our codebase -the Value Object itself plus all parts that know too much about its internals and use them, like in the code above.

The logic that belongs to a VO should be put inside the VO. Adding two StoryPoint is an operation that makes sense only inside StoryPoint because only StoryPoint should know about its internals. That's what attracting behavior means and it does very good work on empowering our code encapsulation and semantics.

Consider this VO-free piece of code:

$age = 21;
$storyPoints = 3;

$somethingVeryWrong = $age + $storyPoints;

When your code works with primitives to handle concepts of your domain (which by the way is a code smell named primitive obsession), the programming language cannot prevent you from doing such things. Types and Value Objects do.

So, how to approach adding Story Points? Putting the add operation in StoryPoint and passing another StoryPoint to be added:

class StoryPoint {
    public function __construct(private int $value) {}

    public function value(): int {
        return $this->value;
    }

    //We are skipping the return type on purpose. Stay tuned!
    public function add(StoryPoint $storyPoint) {}
}

This way we guarantee that nobody knows about the internals of our VO and can nonsensically add random unrelated values to them.

Immutability

When implementing the add operation in our StoryPoint VO we may be tempted to go like the following:

class StoryPoint {
    public function __construct(private int $value) {}

    public function value(): int {
        return $this->value;
    }

    //Don't do this
    public function add(StoryPoint $storyPoint) {
        $this->value = $this->value + $storyPoint->value();
    }
}

For sure we are sticking to the encapsulation, but we are introducing mutability as well. And we mentioned we want our VOs to be immutable when possible. Mutability is something to avoid because it is a source of hard to track bugs. Consider the following:

$fiveStoryPoints = new StoryPoint(5);
$report = new SprintReport();
$report->addCompletedStoryPoints($today, $fiveStoryPoints);
//Can we trust our $fiveStoryPoints are still five?

As long as our StoryPoint public interface (the add method) is changing the state of the instance like in the previous implementation, we cannot guarantee its value was not changed inside the call to addCompletedStoryPoints. Of course, we can open addCompletedStoryPoints and check there is no call to the add method there, but that's a manual approach that does not scale very well.

The way to make our VOs immutable is returning a new fresh VO as a result of the operation. Here is the implementation plus the usage in SprintReport:

class StoryPoint {
    public function __construct(private int $value) {}

    public function value(): int {
        return $this->value;
    }

    public function add(StoryPoint $storyPoint) {
        return new StoryPoint($this->value + $storyPoint->value());
    }
}

class SprintReport {
    private StoryPoint $completedStoryPoints;

    public function addCompletedStoryPoints($date, StoryPoint $amount) {
        $this->completedStoryPoints = $this->completedStoryPoints->add($amount);
    }
}

Although it may seem a waste of memory and resources, those are not aspects we should care bout in the vast majority of the situations -garbage collection will take care of the instances not referenced soon enough- and the value we get in exchange is far more significant.

Some literature claims immutability is not a mandatory aspect of VOs, although highly desirable. To be honest, I've never found a situation where mutability was justified, but it does not mean there are none. As with all the "rules" in software development, it is on the developer's good reasoning to decide when to bend them in a given context. Default to immutable VOs and if you find a scenario where it is not advisable, please let me know :)

Final word

Hopefully, this post has given a good grasp on the benefits the Value Object pattern provides to any OOP codebase, even using a naive example to illustrate it. Introducing them in greenfield applications or code suffering from primitive obsession pays off from the first minute, so I cannot encourage you enough to use them.

In a following article, we will see how to introduce our StoryPoint Value Object in this made-up Jira codebase we have, applying refactoring techniques in baby steps. Probably the two most powerful tools available in OOP. Stay tuned!

Ambiguity hurts communication. And we should care about it

Carlos Gándara — Sun, 13 Dec 2020 20:30:01 +0000

Update from December 2023: Three years after writing this not-so-fortunate post, I deeply regret the title I gave it in the first place (The three most misused terms in software development and how to deal with them), which follows a clickbait pattern so sadly common in the present days. A mix of getting caught in the wave and an absurd thirst for popularity? Probably.

The content was never good, but at least there is an idea somehow worth behind it. I've edited the title to something less crappy. Apologies.

The original content starts here:

There are only two hard things in Computer Science: cache invalidation and naming things.
-- Phil Karlton

Bad naming hurts communication, and communication is a first-class citizen in an activity like software development. Here we will be discussing the three most common -in my personal ranking, although they should appear for a fact in any top ten- wrongly used terms in the development jargon.

Service

This is the absolute winner of the most overloaded term in software development. It covers a range that goes from massive external applications, Facebook as a whole can be an authentication service, to virtually any class in a codebase, when in the context of a service container.

The multiple meanings the word service has are not bad per se. It is a broad term and that's necessary in a world that is that much into abstractions. However, this generality could mean a serious penalty to communication quality if not used in an agreed and seamlessly understood context.

One real personal experience: I spent half an hour totally disoriented in a meeting "to discuss services dependencies" until I realized the services were not the "microservices" I thought, in the context of software architecture, but the relations between "doctor services" in the context of medical activity, like blood analysis, dental surgery, and the like. By the time I got it was too late to catch up.

In several situations there is a better word than service, or it can be expressed together with another word that narrows the meaning to common ground. When we cannot find an alternative, better to settle first what kind of services are being discussed and do it again when the conversation jumps to another type.

Mock

In the context of testing, the broad usage of Mock means a replacement of a dependency of the code being tested to isolate this code from the dependency.

Actually, that's the definition of a test double and the term mock has overtaken its supertype in everyday talking.

Mocks are only one of the five types of test doubles, the most complex of all of them. They have a number of drawbacks and some benefits over other test doubles. I've written a full article dedicated to test doubles if you want to dig more into the differences.

The hitchhiker guide to test doubles

Carlos Gándara ・ Sep 9 '19

#testing #php

The problem is that the indiscriminate use of mock for any kind of test double has created a trend of using them for every situation a double is needed and spreading the belief that they are the only tool available for such purpose. That's not true.

It is important to know as much as possible the tools at your disposal and chose the right one. Mocks have their use cases, use them when they fit, and other doubles when a mock is an overkill (which probably is most of the time by the way).

Refactor

Refactor is "the process of restructuring existing code —changing the factoring— without changing its external behavior" (wikipedia).

However, the common usage refers to "the process of writing code in a place where there was code before". It would be more economic and accurate to say "I am changing code", but we geeks like to sound sophisticated (I guess) and we prefer to wrongly use a word with some echoes of a sci-fi movie, losing the chance to communicate better in the process.

Not changing the external behavior of a piece of code means the same input will produce the same output. How you process this input and calculate this output is the implementation, and what you change when refactoring.

This has a strong link with (well written) tests: when refactoring you don't touch anything on the tests, just the code making them pass. Otherwise, you are changing, updating, expanding, rewriting... Don't use refactor when doing that and miss the opportunity to transmit a precise message of what you are actually doing.

But is it that bad?

It is. Every time we wrongly use one of these terms, or any other for the matter, we lose the opportunity to communicate better. This eventually translates to a waste of time, which is really bad.

At the same time, it would be a tough and pointless battle to try to eradicate them. Mostly because they are the right word to use in certain moments and contexts, and also because their adoption is too deep in the day to day life. However, we should develop the ability to detect when their usage is harming the communication and act accordingly, pointing it out or gently introducing accurate alternatives.

PS: I sincerely apologize for the slightly clickbait title :P

Book review: Just Enough Software Architecture

Carlos Gándara — Sun, 19 Apr 2020 17:15:44 +0000

Last year I attended the first edition of the GSAS conference. The speaker roster was impressive and included George Fairbanks. Was because of it that I decided to read Just Enough Software Architecture, a risk-driven approach.

The outcome of the conference didn't live up to my expectations. The tone felt distant and somehow settling a differentiation between architects and developers, some kind of elitist barrier (and here for sure I am failing to describe precisely my impressions due to lack of English vocabulary). That was weird because most of the talks, the one from Fairbanks included, were not explicitly suggesting it at all.

Turns out I got a similar impression from the book. There is valuable information on it, that's for sure, but the tone and a big part of it feel distant, maybe too academic, despite of Fairbanks efforts to provide meaningful examples and an informal tone.

The book is structured in two main blocks. The first one introduces Risk-Driven Software Architecture, its main highlight and indeed an interesting approach. How you should architect your application based on the risks and quality attributes you know it requires, doing the right trade-offs to find a balance between deliverability and engineering. For instance, do not build an astonishingly scalable system if none of your quality attributes is performance. The way Fairbanks introduces this technique is enjoyable and well-illustrated, with solid examples for all of the standpoints.

The second block, though, is composed of thoroug descriptions of ways of representing models of the architecture, at different levels and with different techniques. This translates to, and I know I am oversimplifying here, diagrams.

Almost two-thirds of the book revolves around levels of detail, types of architecture representations, and the relations between them. The amount of theory and detail is noticeable and it is hard to relate big chunks of content to what I currently need as a software developer ( which might mean this disappointment is caused by a mix of expectations and momentum in my career). It took me a lot of time to finish the book because of the low engagement with this second block, especially after a first one way more practical and concise.

Coming back to the conference perception, there is good stuff in the book and some things I will definitely take into account in my current and future projects. But at the same time, there is something hard to describe about it that made the reading not satisfactory. A contradiction between an approach to architecture encouraging doing just the necessary, and a tour about theoretical aspects of model representations that feel like way more than the necessary.

A first part that relates to software developers and a second part that relates to architects.

About mothers, builders, and how to reduce duplication in your tests

Carlos Gándara — Mon, 03 Feb 2020 18:49:42 +0000

Applying the builder pattern when creating the fixture data in our tests will provide several relevant benefits: better readability, more explicit test scenarios, and resilience to refactors.

It sounds too good to do not give it a try, doesn't it?

Disclaimer: code examples are in PHP but the concepts discussed refer to OOP, so don't get scared by the dollar symbols and the arrows.

Harmless changes with unexpected consequences

A non-desirable but common scenario: an apparently harmless, small change in production code causes zillions of tests to fail. We did stick to SOLID, DRY and plenty of other buzzwords while coding. Then, how can this be possible? Why we have to tediously update several apparently unrelated tests?

There are multiple possible reasons for this to happen. One of them is how we create fixture data in our tests. Consider the following scenario:

We have an application that processes orders, modeled in the Order class:

final class Order 
{
    private Uuid $id;
    private array $items;
    private string $address;
    private DateTime $deliveryDeadline;

    public function __construct(
        Uuid $id,
        array $items,
        string $address,
        DateTime $deliveryDeadline
    ) {
        $this->id = $id;
        $this->items = $items;
        $this->address = $address;
        $this->deliveryDeadline = $deliveryDeadline;
    }

    //Fancy business logic here
}

In production code, we did the smart move of instantiating Order class only in the CreateNewOrder service when creating a new one, or in the OrderRepository when we get an existing order from the database.

As good or bad this modeling may look, our startup is starting to get some revenue out of it. The best part is that the code is extensively tested. For instance, we have this test taken from the more than forty we have involving an Order:

/** @test */
public function order_cannot_be_processed_when_delivery_deadline_is_reach(): void
{
    $order = new Order(
        Uuid::create(),
        [
            new Item('Dynamite Headdy', 1, 6500, 'GOLD'),
            new Item('Gunstar Heroes', 1, 12500, 'GOLD'),
        ],
        'Rincewind, Mage Tower, Ankh-Morpork, 00752, Discworld',
        new DateTime('yesterday')
    );

    self::assertFalse($order->canBeProcessed());
}

Feels good to have business logic properly tested. However, our company is having more and more problems from customers living in some parts of Ankh-Morpork -no surprises- and we want to stop sending stuff to a certain zip codes. For that, we decide to model the address as an Address value object so we can easily evaluate when an order is being delivered to a forbidden zip code:

final class Address
{
    private string $name;
    private string $street;
    private string $city;
    private string $zipCode;
    private string $country;

    public function __construct(...) {}

    public function hasBannedZipCode(): bool {}
}

We write a test for the new behavior:

/** @test */
public function order_cannot_be_processed_when_address_has_a_banned_zipcode(): void
{
    $order = new Order(
        Uuid::create(),
        [
            new Item('Speck of dust', 1000, 2, 'GOLD'),
            new Item('Higgins bosom', 100, 1, 'GOLD'),
        ],
        new Address('Rincewind', 'Mage Tower', 'Ankh-Morpork', self::BANNED_ZIPCODE, 'Discworld'),
        new DateTime('yesterday')
    );

    self::assertFalse($order->canBeProcessed());
}

Changes in the code are straightforward. We implement the canBeProcessed() method using the new Address value object and the new test passes. Now we can expect to update CreateNewOrder and OrderRepository classes to deal with the change in Order constructor. But when we run the test suite we see forty of them in red. Not surprisingly, the ones involving orders.

In our production code, we took care of minimizing the places where we instantiate a new Order (band reference not intended) to reduce the reach of changes like the one we just did, but we forgot about our tests that are instantiating orders all around.

There are other undesirable effects on the approach we took. One is that Order instantiation is causing a lot of noise because of this complexity when we usually care only about one aspect of it -the zip code in the above example. The other is the inability to visually detect if we are messing up the order of the parameters in the address.

Luckily, we are here to see how builders mitigate such situations.

Introducing the builder pattern

The builder pattern is one of the GoF Design Patterns. It consists in separating the -usually complex- construction of an object from its representation.

Twisting it a bit, the suggestion here is to use builders for any object or data structure you create more than once in your tests.

A possible public interface for a builder for our Order might be:

final class OrderBuilder
{
    public function build(): Order {}
    public function withId(Uuid $id) : self {}
    public function withItems(array $items): self {}
    public function withAddress(Address $address): self {}
    public function withDeliveryDeadline(DateTime $deliveryDeadline): self {}
}

The build() method return an Order instance with any setup we define through the withX() methods. Internally we define default values for all the parameters involving instantiating an Order, so we don't need to call all the withX() methods every time -that would miss big part of the point of using these builders.

Our previous test looks now like:

/** @test */
public function order_cannot_be_processed_when_address_if_from_a_banned_zipcode(): void
{
    $address = new Address('Rincewind', 'Mage Tower', 'Ankh-Morpork', self::BANNED_ZIPCODE, 'Discworld');
    $order = (new OrderBuilder)->withAddress($address)->build();
    self::assertFalse($order->canBeProcessed());
}

Way more readable, concise, and explicit about the purpose of the test. Even more, we can have an AddressBuilder as well and reduce all the irrelevant code needed to create a complete address.

If now we need to change anything else in the Order modeling, we have drastically reduced the points we need to change in our tests to do so. For instance, a change from the array of Item to an ItemCollection, so we can filter certain types of items to apply discounts, will require only to change the OrderBuilder, because it is the only point in our test suite we create Order instances. Profit.

Builders are as well very handy to generate plain structures, like request payloads or configuration files, and they do un awesome work removing the mysticism of magic numbers in the tests: it is more understandable withDiscount(10) than a lonely, meaningless 10 in the middle of some constructor call.

Introducing object mother pattern

Object mother is a pattern where a class is used to create example objects, exposing a number of explicit factory methods.

If we start noticing we are building the same Order configuration in several tests we are still duplicating code. For instance, if our orders over 50 total price are susceptible to special discounts and many other advantages, we will do the following setup multiple times:

/** @test */
public function order_has_free_shipping_when_total_amount_is_50_eur_or_more(): void
{
    $item = (new ItemBuilder)->withPrice(51)->build();
    $order = (new OrderBuilder)->withItems([$item])->build();
    self::assertTrue($order->hasFreeShipping());
}

Using an object mother class for order would reduce the previous example to:

/** @test */
public function order_has_free_shipping_when_total_amount_is_50_eur_or_more(): void
{
    $order = OrderMother::ofAmountGreaterThan(50);
    self::assertTrue($order->hasFreeShipping());
}

Object mothers do the same work as builders when it comes to reduce duplication and noise in tests, although we must be careful to don't hide the duplication inside the object mother and bloat it with multiple instantiations of the same class, incurring in the same problem as before -although at a lesser scale, for sure.

Another issue we can run into is starting to use the object mother for everything, even for slight variations of the same data setup, overcharging them with factory methods with names too long to represent to the specificness of each case. A builder would work better in that case.

That said, why not combine both? We can add factory methods to our builders and if they start to become too cumbersome, move all the mother-ish methods to a proper object mother that internally uses a builder. Or have an object mother for builders with setups that we can tweak for concrete, edgy cases. Sky and your needs and context are the limit.

A builder implementation example

This is an example of how you can implement a builder in PHP:

final class MetalSlugCharacterBuilder
{
    private array $base;

    public function __construct() {
        $this->base = [
            'name'   => 'Marco Rossi',
            'weapon' => new RocketLauncher(),
            'bombs'  => 10,
        ];
    }

    public function build(): MetalSlugCharacter {
        return new MetalSlugCharacter(...$this->base);
    }

    public function withName(string $name): self {
        return $this->base['name'] = $name;
    }

    public function withWeapon(Weapon $weapon): self {
        return $this->base['weapon'] = $weapon;
    }

    public function withBombs(int $bombs): self {
        return $this->base['bombs'] = $bombs;
    }
}

Furthermore, I even wrote a small library to reduce the amount of boilerplate and the time required to code a builder, plus some extra goodies. You can check it here:

xoubaman / builder

A lightweight PHP library to build... builders

Summary

Same as we care about avoiding unnecessary repetition in our production code, our tests deserve the same attention, if not more. Builder and object mother are two patterns that will help us to have a more consistent test suite, where tests fail because they should and not because we forgot to update the n-ish instantiation of some class.