
Building software demands engineers regularly evaluate trade-offs. We must research different potential solutions and choose the option we believe best suits our needs. Since we are all human it's reasonable to assume we will choose an approach which accidentally introduces unforeseen challenges from time to time.

This is known as Accidental Complexity.

In this article, I'd like to introduce a form of Accidental Complexity I've been referring to as _Accidental Intent Cancelling_.

---

When a user interacts with our application, they are communicating intent. Imagine a profile screen which contains a form where your address could be updated. Once changes are made, a button labelled "update" can be clicked.

From this viewpoint - everything looks fine.

But if we zoom in, depending upon our choices, the intent of the user to update the address on their profile can be easily lost.

## Example of Intent Cancelling

Imagine we implement a RESTful API to process our example form and make the following request:

```http
PATCH /profile/123
{
    address: '123 The Street, Big City, AB1 2CD',
}
```

Do we still know the intent of the user?

We have a `PATCH` request for a Profile with an ID of `123`. The request contains a new value for `address`. It's clear the user wants to update the address on their profile, right?

No - that was a guess!

We know _what_, but we don't know _why_. Depending upon what is orchestrating the API, anything could be happening - we have no idea! It could be the user updating their address; it could be our customer support team fixing a typo; or it could be an automated update during a Proof of Address process.

We are processing data, not behaviour.

Intent has been lost.


## Accidental Compromises

This is a common trade-off made with a RESTful API design. Unlike with Remote Procedure Calls (RPC) which issues an instruction to an application to perform an action - a RESTful API client makes a request to describe the specific change to the data it wants to see happen.

This is not an article arguing against REST (or urging you to change how you design your APIs). In fact, many other patterns and technologies have a similar trade-off.

The problem I'm highlighting is: **too often intent is lost accidentally**.

Accidental Intent Cancelling may not become apparent until after significant development of a product or feature. Once clear intent is needed, it may require a non-trivial amount of refactoring and investment to regain.

RESTful APIs _"represent state transfer"_ by design. A client is describing the state change required and not behaviour. And this may be perfectly fine. Domains without significant complexity may have no reason to have a more complex interface allowing the process of behavour over data.

> [Most teams I meet have trouble with modeling behavior. They are more comfortable with modeling data.](https://twitter.com/yreynhout/status/1579750607992532993)

If your application has a sufficient level of complexity, it may be best to _"lift the conversation from being data-centric to behavour-centric"_. Instead of state changing being determined from the outside, issue instructions to the application instead.


## Why Intent Is Needed

Let's use our example to explore the difference when modelling data over behaviour. Imagine we are presented with the following business requirement:

_"When a User updates their Address, perform Proof of Address screening."_

We recognise the need to trigger a process when something happens within our system. A new `ProfileAddressWasUpdated` event is published. Now, when this event happens, we start the Proof of Address screening process.

Everything is fine - until bugs are raised that Proof of Address screening is happening unexpectedly. We investigate and discover it happens when our support team make corrections to addresses using our own admin system.

Because our system is unaware of the original intent, we have no way to differentiate requests. We have a webapp, support admin, background processes and mobile clients all making the same request to update data for different reasons.

Greg Young described this as:
> The domain had become a glorified abstraction of the data model.

If only our system modelled behaviour - we wouldn't find ourselves in the situation where we need to refactor our client applications (or worse, introduce a hack) to determine which address change is relevant, and which is not!

## Feature Envy and Tell Don't Ask

We've explored what a data-centric approach may look like, and why the approach may not be desirable. A behaviour-centric approach, instead of describing the state to be changed, describes the action to be taken.

```
POST /profile
{
    command: 'UpdateBillingAddress',
    payload: {
        address: '123 The Street, Big City, AB1 2CD',
    }
}
```

Intent here is captured and sent to the application. We can now easily determine if we are handling an `UpdateBillingAddress` or `CorrectCustomerAddress` use case. Domain-specific events can be broadcasted and we will no longer have the unexpected behaviour from the previous example.

No longer do client applications know specifics about how a behaviour is achieved - it simply sends instructions the correct domain to perform the behaviour and trusts it to handle the details.

I recognise this as **Feature Envy**: an anti-pattern which describes a situation where _"the outside"_ requests internal information in order to perform behaviour.

By following **Tell Don't Ask**, our webapp; support admin; background processes and mobile applications no longer need to know the specifics of a behaviour. They don't need to know the data changes and domain rules do not need to be scattered across all applications.

Instead, behaviour is encapsulated within the domain. Clients can still make an HTTP request to an API. Unlike our previous example, the request will now issue a command containing essential information.

## Consider Intent

Engineers must evaluate trade-offs when making a decision. To make quality decisions, we need as much information as possible. Decision making improves with experience because we have more knowledge and understanding of potential trade-offs and compromises.

The next time you are faced with a decision - be mindful of the role intent plays within your system. Ensure, if you are cancelling intent, it's a conscious trade-off. Otherwise, you may find yourself guessing what the original behaviour of the user was.

At least, consider modelling behaviour as an option.


In this article, I introduce a form of Accidental Complexity I've been referring to as Accidental Intent Cancelling.

Accidental Intent Cancelling


An interesting [article from Matthias Noback](https://matthiasnoback.nl/2022/09/is-it-a-dto-or-a-value-object/) sparked discussion I was involved in recently regarding the differences between Value Objects and DTOs and if it were possible to recognise them from the class definition. And, if so, what aspects help us identify them the most?

Can we identify a Value Object or a DTO from the class definition?

Let's see:

```php
final class Money {
  public function __construct(
      public readonly int $amount,
      public readonly string $currency,
  ) {
  }
}
```

Hmm - it's hard to tell, right? But, why is that?


## Data Transfer Objects

The purpose of a DTO is nicely described within the name - an object designed to transfer data from one place to another.

PoEAA describes a DTO as:

<img src='/posts/IMG_3982.jpeg' alt='PoEAA' class="shadow-md rounded-xl -rotate-2" />

<figure>
    <blockquote>
        <p>An object that carries data between processes in order to reduce the number of method calls.</p>
    </blockquote>
    <figcaption class='text-right'>
        <cite>
            Patterns of Enterprise Application Architecture
        </cite>
        - Martin Fowler
    </figcaption>
</figure>



This sounds like we should gain clues about this object being a DTO or a Value Object based on its usage. If data is being transferred - perhaps we have a DTO?

But, before we venture outside the class, are there any ways to tell from the class itself?


### Commands

One common type of DTO is a Command - an object, named imperatively to describe an action, is used to provided as an instructon to your application. For example `TransferMoney` could provide all the information required to transfer money from one place to another.

```php
$command = new TransferMoney(10, 'GBP');
$commandBus->handle($command);
```

Is `TransferMoney` a DTO? Yes!

We can actually tell this is a Command from the name of the class. Additionally, we see above the object encapsulates all the data required to perform the behaviour and that it transports the data as it's passed into a `$commandBus`.


### Events

What about events?

These objects are named in the past-tense and describe an immutable fact which has happened within a system:

```php
$event = new MoneyWasSent(10, 'GBP');
$outbox->record($event);
```

Is the `MoneyWasSent` object a DTO? Yes!

Here we have an object representing a change within our system. It contains data relating to what changed and will be published (another way of saying "transferred") to any interested subscribers.

We have another DTO!

### Is Money a DTO?

Does this help us decide if `Money` is a DTO?

This was our original example:

```php
final class Money {
  public function __construct(
      public readonly int $amount,
      public readonly string $currency,
  ) {
  }
}
```

We've determined that `TransferMoney` and `MoneyWasSent` are DTOs. Naming helps reveal the object's intent to transfer data. But `Money` doesn't look to be a Command nor an Event. It's neither named imperatively to describe an action, or in the past-tense to represent a change.

Naming can help reveal intent. However, in the case of `Money`, there are no clues as to the object's intended use. We do not have enough information to determine this object is a DTO.


## Value Objects

The purpose of a Value Object is to represent a value important to the business. Typically, they will encapsulate constraints ensuring validity.

### Business Constraints

Imagine we have a business rule requiring `Amount` to be a positive value. We could enforce this constraint within the constructor of the Value Object:
```php
final class Amount {
  public function __construct(
      public readonly int $amount
  ) {
      if ($amount < 0) {
          throw new InvalidArgumentException();
      }
  }
}
```

Now, when we try to `new Amount(-1)`, we will see the error:

```php
PHP Fatal error:  Uncaught InvalidArgumentException
```

In this example, it's impossible for `Amount` to be created in an invalid state.


### Immutability

Another design requirement for Value Objects is immutability.

When we design a class to be immutable, internal state does not change. Instead, when a new value is computed, a new object will be created and returned:

```php
final class Amount {
  public function __construct(
      public readonly int $amount
  ) {
  }

  public function double(): Amount
  {
    return new Amount($this->amount * 2);
  }
}

$one = new Amount(1);  // 1
$two = $amount->double(); // 2
```


### Is Money a Value Object?

Let us once again take a look at our `Money` object to see if we can determine if it's a Value Object:
```php
final class Money {
  public function __construct(
      public readonly int $amount,
      public readonly string $currency,
  ) {
  }
}
```

The constructor of this object takes in an `int` and a `string`. Can we consider this typing enough to protect business rules?

As we discussed before, an `int` could be `-1`, `0` or `10`. Strings could also be blank with `''` and, by the looks of this context, would be invalid if it didn't match a currency code. It depends on your business, but I'm going to say _no_.

Is `Money` immutable? Yes - perhaps this is our first clue this could be a Value Object! We can see both `$amount` and `$currency` are _readonly_ without any public methods which could mutate their state.

Does this mean we have a Value Object? Unfortunately, I don't think so. Immutability, as much as it is a key principle when designing Value Objects, it is not unique to them. It's entirely possible to design a `DTO` to be immutable - for example, we could have a `TransferMoneyRequest` which, once it hits our system from the outside, we do not want its values to change.


## Intent

So far we've only looked inside (the limited) class definition to try to determine if `Money` is a DTO or a Value Object. We have struggled because DTOs and Value Objects can sometimes look very similar. We simply don't know enough about `Money` to determine what it is.

How could we reveal intent within the `Money` object to help our fellow engineers?

- Naming\
Perhaps the most useful tool we have as engineers is how we name things. When thinking about an example I could use for this article, which could be a Value Object or a DTO - I ensured name of class was intentionally vague. When we're naming our classes we should take the opportunity to reveal intent, if we can.

- Namespace\
I intentionally did not include a namespace as it makes it much simpler to determine if an object is a DTO or a Value Object. For example, you'll more likely find Value Objects within a _Domain_ layer. You'll also more likely find Commands within an _Application_ layer. Where your object is placed within your system helps reveal intent.

It's important to remember, we reach for Value Objects or DTOs for different reasons. Value Objects measure, quantify or describe something important within our domain. DTOs transfer data from one place to another - they don't contain business logic

If you are having trouble identifying if a class is a DTO or a Value Object, be sure to check how they are used on the outside - not just their definition. Their reason for existing. Their intent.


## Opinion

Many times articles have no choice than to explain tradeoffs and end articles with _"it depends"_. After all, there are no one-size-fits-all solution when it comes to building software. However, I thought I'd stick my neck out and share my opinion and why I reach that conclusion.

In my opinion, `Money` is a Value Object. Not a good one, though.

In terms of the naming, it looks to be more a _thing_ than a message. The object looks to be a concept within a domain which needs 2 pieces of information in order to make sense. In order to represent money, we need an amount and a currency.

To me, it looks to be a Value Object - but I wouldn't bet any `Money` on it... 🥁


## Conclusion

It can be difficult at times to identify the intent of an object. DTOs and Value Objects have clues, just like other types of objects. The key to identifying them is to first understand their intent and knowing what to look for.

DTOs can sometimes have natural linguistic characteristics which can help reveal intent through a naming convention - particularly for Commands (imperatively named) and Events (past-tense).

Value Objects describe something important within a domain. They represent a value, enforce domain constraints and are often found within a Domain layer.

Is it possible to recognise a class as a Value Object or DTO?

Howdy!