DEV Community: Dirk Groot

Designing with Types #03: Safety and Intent

Dirk Groot — Wed, 09 Jul 2025 11:33:55 +0000

In the previous installment of this series, we concluded that we can write code that is safe and that reveals intent by making illegal states unrepresentable and by encapsulating state changes. Today, we'll try to come up with proper definitions of safety and revealing intent. Also, we'll take a look at more examples of applying these principles in practice.

Safety

What does safety mean in the context of software development in general and designing types in particular? Here's my attempt at a "formal" definition:

We consider an API to be safe if and only if everything that's public can be used freely, without the risk of introducing an illegal state.

With this definition I'm trying to stay as language agnostic as possible. Reason for this is that the concept of safety can be applied (to some extent) to every programming language and every paradigm.

In this series, we're focusing mainly on strong-typed, object-oriented languages like Kotlin and Java. In those languages everything that's public is either a public class, a public method, a public field or (in Kotlin) a public top-level function. To be more specific, this definition applies to everything that causes a state change. Things like read-only fields or pure functions are always safe according to this definition, because those things don't modify anything.

So what does this mean in practice for things that do modify something? Let's look at each case individually.

Public mutable fields can only be freely mutable if there exist zero situations where a possible value of such a field can be considered invalid. If this is not the case, a field cannot be publicly mutable according to this definition.
Public methods and top-level functions that change state may never change that state to something invalid. According to this definition, such methods or functions must either:
- change the state to something valid;
- throw an exception;
- do nothing;
- or return a value that indicates a failure.

Revealing intent

Code is written once, but it's read many times. Therefore we want the code to be easy to understand. For this article series, I'll use a pretty narrow definition of revealing intent:

Code that reveals intent is explicit about what it does, what it expects and what it results in.

I don't think this definition needs much of an explanation. It doesn't just apply to code. Take a typical use case template for example. Such a template will typically have room for us to document the goal, the preconditions and the postconditions. In order to properly understand a piece of functionality, this is what we typically need to know, regardless of whether we're reading code or a use case.

This series is about designing with types, so here we'll be focusing on revealing intent using types. As we'll see, types are a very powerful way of revealing intent. This is because types allow us to give important concepts a proper*name* and because by defining types, we can leverage the power of the compiler to enforce intended usage.

Examples

With the principles from the previous article in mind, let's look at some practical examples. Every example will start by reviewing a piece of code, evaluating whether it's safe and if it reveals intent.

Properties

Code review

Let's look at this Customer class:

class Customer(
    var id: Long,
    var name: String,
    var emailAddress: String,
)

There's no context in this example, but it's not hard to see that this code probably isn't safe:

The id field is publicly mutable, but it's generally not recommended to change the primary key of an entity.
The id field is a plain Long, but negative values are probably not allowed.
The name and emailAddress fields are plain Strings, but it's highly unlikely that every possible String is a valid value for these fields.

Let's assume that in this case, it's safe that name and emailAddress are publicly mutable.

The code does reveal intent to some degree, but it's the bare minimum. It uses helpful names for the properties, but the property types don't reveal any intent at all. The constraints for the id, name and emailAddress are not obvious and it's not clear where we can find those constraints.

Refactoring

The first and most obvious thing we can do to improve the safety of this code, is to make id immutable. By doing this, we eliminate one way to introduce an illegal state:

class Customer(
    val id: Long,
    var name: String,
    var emailAddress: String,
)

We can make id, name and emailAddress safe by introducing Value Objects:

class Customer(
    val id: CustomerID,
    var name: CustomerName,
    var emailAddress: EmailAddress,
)

data class CustomerID(private val value: Long) {
    init {
        require(value >= 0L)
    }
}

data class CustomerName(private val value: String) {
    init {
        require(value.isNotBlank())
    }
}

data class EmailAddress(private val value: String) {
    init {
        require(isValidEmailAddress(value)) // let's pretend we have this function available somewhere 😉
    }
}

Just like in the previous article, we can see the power of the Value Object pattern. With one refactoring, we made two improvements:

The code is now safe. There is simply no way we can write compiling code that introduces an illegal state. The code will either not compile or we'll get an exception for trying to introduce an illegal state. We cannot accidentally swap name and emailAddress, because that code won't compile:
```
val customer = Customer(id = CustomerID(0), name = EmailAddress("name@example.com"), emailAddress = CustomerName("John Johnsson"))
```
We cannot give id an invalid value, because that will throw an exception:
```
val id = CustomerID(-1)
```
The code reveals intent much more clearly. The constructor arguments of Customer all have a type with a proper name, which makes it obvious that acceptable values for those arguments belong to a certain domain. It's also easy to find the constraints for id, name and emailAddress. We simply use our IDE to navigate to the type definitions of the corresponding Value Objects and we'll have all the information we need.

Simple business rules

Code review

Here's an Order class:

class Order(
    val id: OrderID,
    val customerId: CustomerID,
    var status: OrderStatus,
    var paymentId: PaymentID?,
)

Here's a service that makes sure that orders that have not been payed cannot be completed:

class OrderService {
    fun completeOrder(order: Order) {
        if (order.paymentId != null)
            order.status = OrderStatus.COMPLETED
    }
}

The Order class uses Value Objects and id and customerId are immutable, so it's pretty safe, except thatstatus is publicly mutable. We can easily create an order with status OrderStatus.COMPLETED while it has not been payed. We just circumvent OrderService and call the Order constructor directly:

// This code compiles and throws no exceptions
val order = Order(OrderID(1), CustomerID(2), OrderStatus.COMPLETED, null)

The code above communicates intent via OrderService, but Order and OrderService are different classes which are usually defined in different source files, which could belong to different packages. It would be clearer if the data and the business rule were close together.

Refactoring

We can improve this by introducing more encapsulation. We do this by merging OrderService and Order, so we can make the setters for status and paymentId private:

class Order(val id: OrderID, val customerId: CustomerID) {
    var status: OrderStatus = OrderStatus.PENDING
        private set
    var paymentId: PaymentID? = null
        private set

    fun complete() {
        if (paymentId != null)
            status = OrderStatus.COMPLETED
        else
            throw IllegalStateException("Cannot complete an order that has not been payed")
    }
}

With this refactoring we made multiple improvements:

The code is now safe, because all state changes changes are encapsulated inside the Order class. This doesn't compile, because of the private setter for status:

val order = Order(OrderID(1), CustomerID(2))
order.status = OrderStatus.COMPLETED // <- Compiler error

And this raises an exception:

val order = Order(OrderID(1), CustomerID(2))
order.complete() // <- BOOM!

Intent is clearer, because the data and the business rule are defined in one class instead of two.
Intent is also more clear, because the Order constructor contains only fields that are relevant for creating an order in the initial state. All state changes are done using methods like complete (I omitted other methods for brevity).

Statuses

Code review

Coming back to the Order class, let's zoom in on the order status:

class Order {
    var status: OrderStatus = OrderStatus.PENDING
        private set
}

What can we say about such a small piece of code? Well, first of all it looks pretty safe, because the status field has a private setter. What else? Let's look at how we would instantiate this class:

val order = Order()

We've lost some information compared to the class definition. From this constructor invocation alone, it's not obvious what the status of the newly created order is. This is a limitation of constructors in general, because we can't give constructors a descriptive name.

Refactoring

We can improve the communication of intent by introducing a factory method:

class Order(status: OrderStatus) {
    var status: OrderStatus = status
        private set

    companion object {
        fun createPending(): Order = Order(OrderStatus.PENDING)
    }
}

Now, we can instantiate a new Order using the createPending factory:

val order = Order.createPending()

This is clearly an improvement. By using the factory we are explicit about the state of a newly created Order. Unfortunately, there's a downside: We now have a public constructor that accepts any OrderStatus. We have potentially introduced the same safety issue we addressed in the previous example.

Fortunately, the solution is simple. We'll just make the constructor private:

class Order private constructor(status: OrderStatus) {
    var status: OrderStatus = status
        private set

    companion object {
        fun createPending(): Order = Order(OrderStatus.PENDING)
    }
}

Now, the design is safe again. There's only one way to create a new Order, which is via the createPending factory.

Conclusion

We identified two requirements and two design principles to help us write code that is robust and maintainable. The requirements are:

We should design API's so that

they are always safe to use;

they reveal intent.

We can achieve this by using the design principles we discussed in the previous article:

Illegal states should be unrepresentable.

State changes should be encapsulated.

We've seen various examples of how to put this into practice. Until now, the code examples we looked at were rather simple and straightforward. In the next installment we'll conclude this series by looking at a few examples that are less straightforward.

Designing with Types #02: Pitfalls and Practices

Dirk Groot — Mon, 30 Jun 2025 09:32:30 +0000

In this installment of my Designing with Types series, we'll look at how some typical backend code is set up. We'll identify some common pitfalls and identify best practices to avoid these pitfalls.

Architecture

Regardless of what architecture style we use, an application almost always consists of three basic tiers or layers: Presentation, Business and Infrastructure. Here's a diagram that shows two architecture styles using these three layers.

In the Hexagonal Architecture, the Business layer defines ports. The Presentation and Infrastructure layer contain adapters that interact with the web framework and the persistence framework. The Dependency Inversion Principle (DIP) is used to make the Business layer easy to test, because infrastructure-dependent code can easily be replaced by test doubles.

In the classic N-Tier Architecture, the responsibilities of the layers are the same, only the dependency rules are different from the Hexagonal Architecture.

Let's look at some examples of code we often encounter in these three layers.

Infrastructure

As mentioned in the diagram above, this is the layer where database communication usually happens. It's also commonly known as the Data Access or Persistence layer. I'm calling it Infrastructure because it can be used for more than just persistence.

When used for data access, this layer usually consists of database entities and repositories. Here's an example in Kotlin, using JPA annotations for object-relational mapping (ORM) and Spring Data's CrudRepository to generate a repository implementation:

@Entity
data class TodoList(
    @Id val id: UUID,
    var name: String
) {
    @OneToMany(mappedBy = "todoList", cascade = [CascadeType.ALL])
    val items: MutableList<TodoItem> = mutableListOf()
}

@Entity
data class TodoItem(
    @Id val id: UUID,
    @ManyToOne
    @JoinColumn(name = "todolist_id", nullable = false)
    val todoList: TodoList,
    var title: String,
    var dueDate: LocalDateTime? = null,
    var done: Boolean = false,
)

@Repository
interface TodoListRepository : CrudRepository<TodoList, UUID>

@Repository
interface TodoItemRepository : CrudRepository<TodoItem, UUID> {
    fun findByTodoListId(id: UUID): List<TodoItem>
}

Business

This layer contains the business logic of the application. Its responsibility is to make sure that business rules are enforced in the application. It usually consists of services that perform a certain task, using repositories and entities from the Infrastructure layer.

Here's a simple service that can create and remove todo lists (again, in Kotlin):

class TodoListService(val repository: TodoListRepository) {
    fun createTodoList(name: String): TodoList {
        require(name.isNotBlank()) { "Name cannot be blank" }

        val todoList = TodoList(UUID.randomUUID(), name)
        repository.save(todoList)
        return todoList
    }

    fun removeTodoList(todoListToRemove: TodoList) {
        if (todoListToRemove.items.any { !it.done }) {
            throw TodoListNotRemovableException()
        }
        repository.delete(todoListToRemove)
    }
}

This is a common pattern in these services. They check some business rules and if everything is okay, an action is performed. In this example, the business rules are that a todo list must have a name and that a todo list may only be deleted if all its todo items are done.

Here's an example that creates a new todo item:

class TodoItemService {
    fun create(id: UUID, description: String, dueDate: LocalDateTime?): TodoItem {
        if (dueDate != null && dueDate.isBefore(LocalDateTime.now()))
            throw InvalidDueDateException()

        val todoList = todoListRepository.findById(id).orElseThrow { TodoListNotFoundException() }
        val todoItem = TodoItem(id, todoList, description, dueDate)

        todoList.items.add(todoItem)
        todoListRepository.save(todoList)

        return todoItem
    }
}

In this example, besides input validation, we also ensure that we don't try to add a todo item to a list that does not exist.

Presentation

In the variants mentioned earlier, the Presentation layer contains presentation and application logic. Alternatively, presentation and application logic can be assigned to separate layers. It contains functionality that is used by end users and uses the Business layer to validate and execute actions that users request. In a backend application that exposes a REST API (for example for a frontend or external systems), this layer contains REST controllers.

Here's an example of a REST controller, using annotations from Spring Web:

@RestController
@RequestMapping("/api/v1/todo/list")
class TodoListResource(private val todoListService: TodoListService) {
    @PostMapping
    fun create(@RequestParam name: String): ResponseEntity<TodoListRestModel> {
        val todoList = todoListService.createTodoList(name)
        return ResponseEntity.status(HttpStatus.CREATED)
            .body(TodoListRestModel.from(todoList))
    }
}

The Business layer is used to create and store the new todo item. The controller makes sure that a HTTP response is returned, containing the newly created todo item.

Code review

These code examples are pretty simple and straightforward. That's because the problem domain and the associated business rules are simple. You could argue that this code is perfectly fine for such a simple application, and I would agree.

Still, I'd like to review this code with one important question in mind: Does it scale? Features will be added and existing features will be expanded. Systems grow bigger and more complicated, and so does the code. Ideally, we want our code to be designed in such a way that it stays maintainable while the system grows.

Duplication

While not directly obvious in the code above, we can see that we're setting ourselves up for code duplication. For example, let's expand our TodoListService with the ability to rename an existing todo list:

fun createTodoList(name: String): TodoList {
    require(name.isNotBlank()) { "Name cannot be blank" }
    // ...
    return todoList
}

fun renameTodoList(id: UUID, name: String) {
    require(name.isNotBlank()) { "Name cannot be blank" }
    // ...
}

Now we have two functions that accept a name for a todo list. Obviously, a String can be blank, which we don't want, so every time we use a String for accepting the name of a todo list, we need to check if that String contains a valid name.

This problem arises when parameter types accept more values than the domain we're implementing allows for. If that's the case, we need input validation to make sure our function is not used in an invalid way. This is an anti-pattern, called Primitive Obsession. Be aware that this isn't limited to the usage of primitives. In general, when we use overly permissive parameter types, we likely need input validation.

Public mutable state

Some of the state of entities in the Infrastructure layer can be changed by everyone. Take TodoItem for example:

@Entity
data class TodoItem(
    @Id val id: UUID,
    @ManyToOne
    @JoinColumn(name = "todolist_id", nullable = false)
    val todoList: TodoList,
    var title: String,
    var dueDate: LocalDateTime? = null,
    var done: Boolean = false,
)

The fields title, dueDate and done have a public setter. This means it's very easy to write code that violates business rules that are normally enforced by the Business layer. For example, we can easily introduce code that changes a todo item to have an empty title or creates a new todo item with a dueDate in the past.

This is an anti-pattern known as Inappropriate Intimacy or Object Orgy.

Lack of encapsulation

The issue of public mutable state is a consequence of another design issue: Data and business logic are separated between different classes. Data is modeled as entities, services make sure that the data conforms to the business rules. The entities shown here are basically Data Transfer Objects (DTO's). They tell the Object-Relational Mapper (ORM) what tables exist, which columns these tables consist of, et cetera.

These DTO's are used thoughout the entire code base. While the Business layer should be enforcing business rules, it's very easy to violate business rules by changing DTO's in a REST controller, for example.

We're using an object-oriented (OO) language, but by designing our code like this we don't benefit from one of the main strengths of OO, which is that data and the associated behaviour are encapsulated in one class. This makes our code more error-prone than it needs to be.

There's a bug!

Maybe you already spotted it, there's a bug in TodoItemService. Can you find it?

fun create(id: UUID, description: String, dueDate: LocalDateTime?): TodoItem {
    if (dueDate != null && dueDate.isBefore(LocalDateTime.now()))
        throw InvalidDueDateException()

    val todoList = todoListRepository.findById(id).orElseThrow { TodoListNotFoundException() }
    val todoItem = TodoItem(id, todoList, description, dueDate)

    todoList.items.add(todoItem)
    todoListRepository.save(todoList)

    return todoItem
}

I've shown this code in several talks I've given, asking the participants to spot the bug. From my limited "testing" it seems that the bug is surprisingly hard to find just by looking at the code.

Now, where's the bug? It's in this line:

val todoItem = TodoItem(id, todoList, description, dueDate)

The id that is passed to the constructor is the id of the containing TodoList! Let's assume the database table for todo items has a proper primary key or a unique constraint. If that's the case, this code will fail as soon as we try to add a second TodoItem to a TodoList, because a duplicate key will be inserted.

This is another example of Primitive Obsession. While UUID isn't a primitive type in the strict sense of the word, it is a type that doesn't tell us anything about what kind of ID it actually represents. When we see just a UUID, it can be hard to determine if it's the ID of a todo list, a todo item, or something entirely unrelated to the domain.

Fun fact: This is a bug that I accidentally introduced when I was preparing this code for a talk. I decided to include it in the talk as an example of how Primitive Obsession can easily lead to bugs that can be hard to find.

Smells

To summarize, in these code examples we have identified a couple of code smells:

Primitive Obsession - By using primitives or other overly permissive types, we need to duplicate input validation. Also, it's very easy to introduce bugs when multiple domain concepts are implemented using the same primitive type.
Inappropriate Intimacy - Unrestricted write access to the state of an object can easily lead to violation of business rules.
Lack of encapsulation - Data and behaviour are separated into different classes.

Principles

One way we can address the issues we found is by designing better types. In this chapter I'd like to provide some high-level principles and practices to help in designing better types. In future installments, we'll explore these more in-depth.

I'd like to mention two principles that I think are fundamental to designing with types. The principles are:

Illegal states should be unrepresentable
State changes should be encapsulated

Illegal states should be unrepresentable ¹

When writing code, the very first feedback we get about our code is from the compiler. This is the shortest possible feedback loop we can have.

For example, when we try to assign a string to an integer variable, the compiler will immediately complain.

val i: Int = "Hello World!" // <-- Compiler error

So the idea behind this principle is that in order to make our feedback loop as short as possible, we prefer compile-time validation over runtime validation. We do this by designing types in such a way that it is impossible to write compiling code that introduces an illegal state.

State changes should be encapsulated

Whenever we're using an object, we should be confident that the state of that object is valid. It's hard to be confident about this when the state of an object is freely mutable by everyone. This is why we use encapsulation in OO.

So this principle means that we should make each class exclusively responsible for enforcing its own invariants. This implies that each class should have exclusive control over its own state changes.

Principles in practice

So how do we put these principles into practice? Let's look at two simple examples.

Value Object pattern

This is such a simple design pattern, but it's oh so powerful! A value object represents one single value. This can be a complex value consisting of multiple fields (i.e. amount and currency for money).

A value object must conform to the following rules:

It is immutable
It is self-validating
The identity of the object is the value itself

Let's look at two examples:

data class Name(private val value: String) {
    init {
        require(value.isNotBlank()) { "Name cannot be blank" }
        require(value.lines().size == 1) { "Name must have exactly one line" }
    }
}

data class Description(private val value: String) {
    init {
        require(value.isNotBlank()) { "Description cannot be blank" }
    }
}

Here we have two value objects, Name and Description. Both classes encapsulate an immutable value. Both classes make sure that no invalid value is accepted. This is arguably the simplest possible example of encapsulation, but there are profound consequences:

Functions that accept a Name and/or a Description as a parameter don't need input validation for these parameters, because that's what the constructors have already done. We can safely assume that the arguments are valid.
We write fewer tests, because if we don't need input validation, we don't need to unit tests input validation.
We can't confuse parameters. The following code does not compile, because we cannot pass a Description when a Name is expected.

  class TodoList(val id: TodoListID, name: Name)

  fun main() {
      // Compiler error
      val list = TodoList(TodoListID.create(), Description("Description\nwith multiple lines"))
      // ...
  }

So here we see both principles in practice. We make illegal states unrepresentable because we cannot confuse values with different domains. The values in the value objects are encapsulated and guaranteed to be valid, which simplifies our code by eliminating the need for duplicated input validation.

Encapsulation using sum types

Here is a slightly more advanced example using a sum type:

sealed interface TodoItem {
    val id: TodoItemID
    val description: Description

    data class Todo(override val id: TodoItemID, override val description: Description) : TodoItem {
        fun updateDescription(newDescription: Description) = this.copy(description = newDescription)
        fun markAsDone() = Done(id, description)
    }

    data class Done(override val id: TodoItemID, override val description: Description) : TodoItem
}

In this example, we model TodoItem as a value object. The states (todo and done) of a todo item are modeled as implementations of the TodoItem interface. The signatures of these types reveal that the description of a todo item in the todo state can be changed. Todo items that are done cannot be changed at all².

This is another way we can make illegal states unrepresentable using types. In fact, we take it a step further because thanks to the sum type, we also make illegal state changes unrepresentable. The following code does not compile:

val item: TodoItem = TodoItem.Done(TodoItemID.create(), Description("Do the laundry"))
val changed: TodoItem =
    when (item) {
        is TodoItem.Done -> item.updateDescription(Description("Do the dishes")) // <-- Compiler error
        is TodoItem.Todo -> item
    }

The sum type forces us to check the state of the todo item, before attempting to do anything with it. If we don't, the code simply won't compile. Code that tries to change the description of a done todo item also doesn't compile.

Conclusion

A lot of the code I've seen and written during my career suffers to some degree from the problems mentioned in this article. As said, in simple, small systems there's little harm in having some Primitive Obsession or lack of encapsulation. In such cases adding a lot of types can feel like overengineering. This is fine, as long as you are aware that the antipatterns can become problematic when the system grows.

By designing better types, we can make our code safer to use and easier to understand by explicitly revealing intent. In this article we've seen two simple examples of this.

Next up, we'll talk some more about safety and revealing intent and we'll look at more examples of using types to our advantage.

This phrase was coined by Yaron Minsky. Scott Wlaschin wrote a very nice article about this, as part of his article series on designing with types using F#. ↩
For the Kotlin-savvy among you: Yes, I know about copy 😄. We'll address that in a future installment of this series. ↩

Designing with Types #01: Introduction

Dirk Groot — Wed, 21 May 2025 11:44:48 +0000

Ever had that sinking feeling when a bug sneaks into production, despite all your testing efforts? Yeah, we've all been there! While languages like Java, C#, and Kotlin come with powerful type systems, many developers aren't using them to their full potential.

In this series, we'll explore how we can use types to catch bugs before they even have a chance to become bugs. We'll look at practical ways to make our designs safer and easier to understand.

Introduction

This is the first part of a series of articles I'm writing about designing with types. In the first two articles we'll set the stage. In subsequent articles we'll explore some practical ways of using types make our code safer and easier to understand.

Feedback loops

Before we dive in, let's consider why this is relevant. While developing software, we are constantly faced with feedback loops. The diagram below shows a simplified version of a typical development process.

This diagram shows three types of feedback we could get after we make a change. The build pipeline could fail, a code reviewer could give valuable feedback, or someone could find a bug while manually testing the change.

From this small example, we can easily see that we're more productive when we have short feedback loops. Solving the bugs we inevitably introduce takes longer when more steps are between making the change and receiving feedback. If receiving feedback takes a long time, we'll go do something else in the meantime. This causes context switching which, as we know, is a big productivity killer.

Finding bugs

Development processes like the one shown above typically have multiple ways of finding bugs after they have been introduced. For example:

Code review
Automated tests
Manual / exploratory tests
Acceptance test
Collect end user feedback
etc...

We need to do stuff like this. If you're doing all this, good job!

Preventing bugs

There are also multiple ways to prevent bugs from occurring in the first place, for example:

Backlog refinement
Developing in small, safe steps
Test-Driven Development
🎇 Design 🎇

Design is what this series is about. We'll explore several ways of using carefully designed types to make illegal states unrepresentable¹. Code that introduces an illegal state should not compile.

Design

Strategy

As shown before, we typically spend a lot of time and effort on finding bugs in our software. This is a good thing. Mistakes will always be made and cannot be 100% prevented, not even by the techniques we'll be exploring in this series. However, from what I've seen "in the wild", I do think we tend to miss a lot of opportunities to design our software in ways that prevent bugs from being introduced.

The overall strategy we'll be exploring is to prevent bugs by carefully designing a domain model. This domain model implements business rules and should be considered an API that is used by our application logic. The domain model should consist of carefully designed types that make it impossible to build application logic that introduces illegal states in our application. Ideally, mistakes in our application logic are found by the compiler.

Design goals

In short, the design goals for our domain model are to create an API that:

is safe to use
reveals intent

Safety

One common cause of bugs is misusing the API of the domain model. Some examples are:

Assigning invalid values to properties
Changing a property of an entity while not allowed
Changing the "workflow" status of an entity while not allowed
Calling functions while not allowed
Having functions without proper input validation and calling them with invalid parameter values

All of this can and will happen, when the API's we design allow for such mistakes to be made.

So what do I mean when I say we should design APIs that are safe to use? It means we should aim to design API's that can be used without having to wonder whether they are safe to use in a particular situation. To achieve this, we should prefer compile time validation over runtime validation. When you use an API in an invalid way, the code should not compile.

Revealing intent

Problems like the ones mentioned above also tend to happen when developers misunderstand the intended purpose of APIs. An obvious reason for this is lack of proper naming. For example, completeOrder reveals a lot more intent than setStatus.

Another, more subtle, naming problem is that we tend to just not name things. We'll be looking at several examples of this in subsequent articles. As a preparatory exercise, you can look at the code you're working on and see if you can find concepts that are implemented, but not explicitly named.

As you will see, safety and revealing intent often go hand in hand. When we improve the safety of your code, we will likely also make the code easier to understand and vice versa.

Next up

In the next article we'll do some more setting the stage by reviewing some commonly seen code. In subsequent articles we'll explore ways of improving the safety and readability of our code.

This phrase was coined by Yaron Minsky ↩

DEV Community: Dirk Groot

Designing with Types #03: Safety and Intent

Safety

Revealing intent

Examples

Properties

Code review

Refactoring

Simple business rules

Code review

Refactoring

Statuses

Code review

Refactoring

Conclusion

Designing with Types #02: Pitfalls and Practices

Architecture

Infrastructure

Business

Presentation

Code review

Duplication

Public mutable state

Lack of encapsulation

There's a bug!

Smells

Principles

Illegal states should be unrepresentable 1

State changes should be encapsulated

Principles in practice

Value Object pattern

Encapsulation using sum types

Conclusion

Designing with Types #01: Introduction

Introduction

Feedback loops

Finding bugs

Preventing bugs

Design

Strategy

Design goals

Safety

Revealing intent

Next up

Illegal states should be unrepresentable ¹