#Domain-Driven-Design - freeCodeCamp.org

How (and why) to embed domain concepts in code

Cedd Burge — Tue, 12 Nov 2019 07:48:19 +0000

Code should clearly reflect the problem it’s solving, and thus openly expose that problem’s domain. Embedding domain concepts in code requires thought and skill, and doesn't drop out automatically from TDD. However, it is a necessary step on the road to writing easily understandable code.

I was at a software craftsmanship meetup recently, where we formed pairs to solve a simplified Berlin Clock Kata. A Berlin Clock displays the time using rows of flashing lights, which you can see below (although in the kata we just output a text representation, and the lights in a row are all the same colour).

Initial Test Driven solution

Most pairs used inside out TDD, and there were a lot of solutions that looked something like this (complete code available on GitHub).

def berlin_clock_time(julian_time):
    hours, minutes, seconds = list(map(int, julian_time.split(":")))

    return [
        seconds_row_lights(seconds % 2)
        , five_hours_row_lights(hours)
        , single_hours_row_lights(hours % 5)
        , five_minutes_row_lights(minutes)
        , single_minutes_row_lights(minutes % 5)
    ]

def five_hours_row_lights(hours):
    lights_on = hours // 5
    lights_in_row = 4
    return lights_for_row("R", lights_on, lights_in_row)

# ...

This type of solution drops out naturally from applying inside out TDD to the problem. You write some tests for the seconds row, then some tests for the five hours row, and so on, and then you put it all together and do some refactoring. This solution does expose some of the domain concepts at a glance:

There are 5 rows
There is one second row, 2 hour rows and 2 minute rows

Some more concepts are available after a bit of digging, but aren't immediately obvious. The rows are made up of lights that can be on (or presumably off), and that the number of lights on is an indication of the time.

However there are some big parts of the problem that are not exposed. And since I haven't yet explained it, you probably don't know exactly how the Berlin Clock works yet.

Elevate the concepts

To improve this we can bring some of the details that are buried in the helper functions (such as get_five_hours) closer to the top of the file. This brings you to something like the following (complete code available on GitHub), although the downside is that it breaks nearly all of the tests. Solutions like this are rarer on GitHub, but do exist.

def berlin_clock_time(julian_time):
    hours, minutes, seconds = list(map(int, julian_time.split(":")))

    single_seconds = seconds_row_lights(seconds % 2)
    five_hours = row_lights(
        light_colour="R",
        lights_on=hours // 5,
        lights_in_row=4)
    single_hours = row_lights(
        light_colour="R",
        lights_on=hours % 5,
        lights_in_row=4)
    five_minutes = row_lights(
        light_colour="Y",
        lights_on=minutes // 5,
        lights_in_row=11)
    single_minutes = row_lights(
        light_colour="Y",
        lights_on=minutes % 5,
        lights_in_row=4)

    return [
        single_seconds,
        five_hours,
        single_hours,
        five_minutes,
        single_minutes
    ]

# ...

This improves the concepts that are now exposed at a glance:

There are 5 rows
The seconds row is a special case
There are 2 hour rows and 2 minute rows
The rows use different colour lights
The rows have a different number of lights

This is pretty good, and is already better that most of the solutions out there. However, it's still a bit mysterious how the rows are related to each other (there are 2 rows to display the hours and the minutes, so presumably these are linked). It's also not obvious what amount of time each light represents.

Name implicit concepts

At the moment some of the concepts (such as the amount of time each light represents) are implicit in the code. Making these explicit, and naming them, forces us to understand them and to embed that understanding in the code.

In order to make the amount of time each light represents explicit, it seems like it would be sensible to pass a time_per_light value to row_lights. This means we have to push the calculation of lights_on down into row_lights.

This in turn makes it obvious that there are two kinds of rows: one related to the quotient (\\) of the time value, and one related to the remainder / modulus (%). If we look at the quotient case, we see that the 2nd parameter to the operation is the time_per_light, which is 5 in both cases (5 hours in one case and 5 minutes in the other).

This allows us to write these rows like this:

five_hour_row = row_lights(
    time_per_light=5,
    value=hours, 
    light_colour="R",
    lights_in_row=4)

If we now turn our attention to the remainder case, we realise that time_per_light is always singular (one hour or one minute), as it is filling in the gaps in the quotient case.

For example, the five hours row can represent 0, 5, 10, 15, or 20 hours, but nothing in between. In order to represent any hour, there must be another row to represent +1, +2, +3 and +4. This means that this row must have exactly 4 lights, and that each light must represent 1 hour.

This implies that the remainder case is dependent on the quotient one, which most people would describe as a parent / child relationship.

With this knowledge in hand, we can now create a function for the child remainder rows, and the solution now looks like this (complete code on GitHub):

def berlin_clock_time(julian_time):
    hours, minutes, seconds = list(map(int, julian_time.split(":")))

    return [
        seconds_row_lights(
            seconds % 2),
        parent_row_lights(
            time_per_light=5,
            value=hours, 
            light_colour="R",
            lights_in_row=4),
        child_remainder_row_lights(
            parent_time_per_light=5,
            value=hours,
            light_colour="R"),
        parent_row_lights(
            time_per_light=5,
            value=minutes, 
            light_colour="Y",
            lights_in_row=11),
        child_remainder_row_lights(
            parent_time_per_light=5,
            light_colour="Y",
            value=minutes)
    ]

# ...

A quick glance at this code now reveals nearly all the domain concepts

The first row represents the seconds and is a special case
On the second row each "R" light represents 5 hours
The third row shows the remainder from the second
On the fourth row each "Y" light represents 5 hours
The fifth row shows the remainder from the fourth

This took something thinking about, which will have cost us some time / money. But we increased our understanding of the problem while we did it, and most importantly we embedded that knowledge in to the code. This means that the next person to read the code will not have to do this, which will save some time / money. Since we spend about 10 times longer reading code than we do writing it, this is probably a worthwhile endeavour.

Embedding this understanding has also made it harder for future programmers to make mistakes. For example, the concept of parent / child rows didn't exist in earlier examples, and it would be easy to mismatch them. Now the concept is plain to see, and the values are mostly worked out for you. It is also easier to refactor to support new clock variants, for example where lights in the first hours row represent 6 hours.

How far should you take it?

There are things we can do to take this further. For example the parent_time_per_light of a child row must match the time_per_light of its parent, and there is nothing enforcing this. There is also a relationship between time_per_light and lights_in_row for the parent rows, and again it is not enforced.

However, at the moment we are only required to support one clock variant, so these probably aren't worth doing. When a change is required for the code, we should refactor so that the change is easy (which might be hard) and then make the easy change.

Conclusions

Embedding domain concepts in code requires thought and skill, and TDD won't necessarily do it for you. It takes longer than a naive solution, but makes the code easier to understand, and will very likely save time in the medium term. Time is money, and finding the right balance of spending time now versus saving time later is also an important skill for a professional programmer to have.

Event sourcing essentials you need to know when starting out

freeCodeCamp — Fri, 15 Mar 2019 18:47:14 +0000

By Noël Widmer

Event Sourcing is a thought challenge when starting out. In this story, I will describe my experiences from the perspective of an engineer.

My goal is to help you decide if you want to invest the resources to get started with Event Sourcing.

_[The Matrix](https://www.amazon.com/Complete-Trilogy-Reloaded-Revolutions-Blu-ray/dp/B001CEE1YE/ref=sr_1_6?keywords=the+matrix&qid=1550756146&s=movies-tv&sr=1-6" rel="noopener" target="blank" title="): Neo is offered a choice.

About The Author

Hi ? I’m Noël. I live near Zurich (Switzerland) and am proudly working on Switzerland’s largest E-Commerce platform. My team and I have applied Event Sourcing throughout the last 12 months, and we learned a lot.

I want to share four essentials with you that I wish we knew one year ago.

A Tiny Introduction To Event Sourcing

This article is not about introducing you to the concepts of Event Sourcing.
I still feel like I should take one step back though — to paint a clearer picture.

In state-oriented applications, you store the result of some computation in your data store. You might also keep a log where you archive old states for auditing or debugging purposes. But by storing state you lose the information about the transition from one state to the other. If a user’s username has disappeared, you’ll be wondering how that could have happened.

Storing state in a state-oriented application.

Sourcing events preserves that information. This is achieved by storing state transitions rather than the resulting state.

Storing state transitions (events) in an event sourced application.

The current state can be restored by applying all events to an empty canvas. That means we can still access the current state but need to invest computational resources to do so.

There are many articles on the web that go into more detail. Martin Fowler wrote one about it. And Greg Young talks a lot about Event Sourcing. Greg is so obsessed with event sourcing that he implemented a data store which is specifically designed for event sourcing. My team is using Greg’s event store — it’s great!

1) Event Sourcing Is Not A Silver Bullet

Once you fall for the bitter sweet taste of Event Sourcing it becomes compelling to apply the concept to all your problems.

This will provide you with loads of data to analyze and you will have a powerful foundation to detect interesting correlations in it. You’ll be able to detect inefficient processes and make them more efficient.

And every engineer’s (my) favorite:

Tracking down a bug becomes much easier when you can “time travel” to the exact moment when the bug happened. In the end you will save time and money.

Well — not quite. ☝️

Sourcing your events sure allows you to do the analysis. But you still need to do it. This will cost time. Luckily, “time travel” comes for free. Enhanced debugging is thus guaranteed from day one.

Seth Godin wrote a great blog post on the subject. It’s a 2 minute read, so check it out.

Now you know about the price you’ll pay if you use your events for analytical purposes which is the main business benefit of Event Sourcing after all.

There is another cost though. Event Sourcing will increase the complexity of your application. Instead of dealing with your application’s current state you’ll have to deal with everything that has ever happened since it went live. Events that are no longer used will remain in your data store and you’ll have to support them for a long time.

It’s great if you deploy a feature and keep iterating on it. Just be aware that there are now multiple versions of that feature’s events in your data store and you’ll have to support all of them. Even if you no longer create new instances of those events.

Event Sourcing imposes additional time complexities that you will have to get used to. Apply it where you see a non-zero chance that the collected data becomes relevant. Where I’d define “relevant” as:

the data could give you more insight into your domain
the data could help your business to improve their processes on their own
the data could help you find bugs faster

Note that I added the word “could” in each of the last three bullet points. It’s likely you won’t know the exact benefit of Event Sourcing in advance. Make your best guess.

2) Recognize The Functional Nature Of Event Sourcing

The authors of the famous Patterns, Principles, and Practices of Domain-Driven Design recommend object-oriented programming languages like C# or Java.

I assume that the implicit reasoning behind that recommendation is the number of people using such languages. It’s true. New team members will likely have an easier start into the domain when confronted with familiar languages.

But I disagree. So does Greg Young. Event Sourcing is not an object-oriented concept.

One might argue that state transitions are objects too. And indeed. You can model everything as objects. Just because you can does not imply that this is the best model to use.

Consider using a language that supports functional paradigms. Especially tagged unions and pattern matching are extremely valuable. Working with your events will feel natural and you won’t have to fight your language’s type system. If your team has no experience with the functional world it might be best to stick to familiar languages though.

Even more important to understand is that choosing a relational data store will be a painful experience. You’re not dealing with relational data when sourcing your events. Each event has its own schema which can change over time. Using a relational data store will hurt.

SQL is the master of nothing but it sucks at nothing. - Greg Young

3) Expect A Steep Learning Curve

As with all new things there will be learning involved. Don’t try to sidestep it. That won’t work.

A great way to learn is to prototype. Try this:

build at least one prototype of your first event sourced application
run and observe your prototype for a while
implement new features and get used to iterating on what you’ve built

Iterate as often as possible before your go live. Once you are live it won’t be as easy to implement new learnings.

Go live once your team feels confident with maintaining the application.

Also think about how your team will introduce new team members to Event Sourcing. New joiners are already in an overwhelming position and learning new concepts won’t make it any easier for them.

Figure out a way to introduce them to Event Sourcing in a soft and safe way. This is important to figure out once you start getting new team members. It’s fine to delay it until that happens.

4) Prepare for political debates

Have you realized that your company wants cheap and quality results today?

Oh my, who am I talking to — of course you did. ?

Will they like it when you experiment with a mind-bending concept they might never heard of? And what is your company’s tech stack like? Do you usually use object-oriented programming languages in combination with relational data stores? Will they like it when you switch to a functional tech stack?

Depending on your companies culture you might have to fight your colleagues on multiple fronts. Act as an example. Tell the truth. You know it will be hard, especially in the beginning. Share your concerns. Make sure everyone involved knows the risks and what you’ll do to prevent them.

And don’t leave out how you picture the Event Sourcing paradise. Get the business on board by allowing them to build reports based on your valuable events. They’ll love it.

Get the concerned engineering people on board by sharing the improved debugging experience. Engineers are stubborn, they might still not like it.

I found it useful to practice such debates with my colleagues. Establish a safe environment for training and encourage your team members to take part.

Be ready and know your stuff. You’ll make it! ?

Conclusion

Let me summarize.

More data isn’t always good.
Additional data without the time to analyze it is useless.
Analysis without the intention and time to act on the result is useless.
Event Sourcing enhances the ability to debug your application.
Event Sourcing is a functional paradigm.
Expect a steep learning curve.
Not everybody will be happy about your plans.

That’s it. My intention was to prepare your expectations to my experiences. Don’t worry. Be determined and choose the red pill!

The Matrix

All images in this story are borrowed from the movie The Matrix.

I’ve spent 9 years writing object-oriented code and working with relational data stores. About two years ago I started to experiment with functional code and non-relational data stores. The mind shift has been one of the most important lessons in my career to date.

Question your environment. Find the flaws. Exit the Matrix and get to experience a whole new world.

Farewell. Until next time. And good luck!

I only write about programming and technology. If you follow me, I won’t waste your time. ?