How to Design Business Objects
Objects are heart of object oriented design and development obviously, but not only. Objects are the center of the enterprise applications and systems, and in this context we refer to them as Business Objects. Other authors call these many different names (e.g. business entities) when explaining different patterns, practices and recommendations, but here I donâ€™t want to create associations with other paradigms that may be the source of those terms (such as DDD). Letâ€™s just call them Business Objects, or just Objects. Reason for insisting this is that, I don't want to create or endorse an incorrect opinion that these object design patterns and practices are only relevant to the specific approaches. Remember that DDD and other similar terms only refer to the set of recommendations, and this is not a "All or Nothing" decision whether to use these recommendations. Point of this statement is, if you have poor object design in your projects that requires improvement, don't say "but we are not following DDD", because this is quite silly excuse.
Itâ€™s unfortunate to see how the importance of Business Objects is downgraded by poor designs, and their purpose is not correctly fulfilled. Reason behind this is engineers being unaware of the proper object designs, or not willing to be better educated on the topic at all. As a consequence, most of the software that is developed as of now, is full of bugs, or hard to understand, or hard to maintain and extend with new capabilities. Itâ€™s surprising that many engineers believe that this is the way the software is supposed to be, but itâ€™s not. My strong belief (based on my experience) is that developing a software and keeping it in the maintainable state is as simple as following correct patterns and design guidelines for the heart of your systems, and mostly for business objects. You may not see the connection between these issues and Business Objects, but I do. I believe that correctly designed business objects can solve most of the problems that I mentioned.
In this article, I will try to draw the connection between problematic software projects and incorrect objects inside them; I will also outline the ways to solve these issues.
What is Wrong with Objects in Most software Projects
Here is the problem I'm describing: itâ€™s very common to see objects designed as simple data containers (a.k.a. property bags, with all its properties readable and writable at the same time), and then there are numerous â€œsmartâ€ classes that create such objects, manipulate them in all sorts of ways, pass them around, again manipulate them, and then destroy these objects when the time comes. 99% of the software systems that I have looked into (and I have looked into many systems) are written exactly like this â€“ with â€œsmartâ€ classes. I bet you have seen (and most likely have written) such software too.
This design is easy to understand by all engineers of all levels (juniors, seniors, architects) when explained as a pattern. For the newly born software projects, this approach also helps deliver first few features faster than the "right approach" (which I'm about to explain later), and this sounds like another benefit for it, and quite tempting argument to start with it. But please don't be fooled - when the project matures and the codebase grows, the pace of delivering new features slows down exponentially, requiring constant analysis of the code from every engineer who is new to the team, or who is unaware of every little detail that happens in the system. If you have a team of couple of engineers, and if you are planning to keep them with this same project forever, then maybe this is the right choice for you. However, in real world, engineers come and leave companies, and thus the project goes through many hands before its completion. In such situations, the mentioned approach is going to suck up budget, time, and resources, so I strongly recommend against it.
Here are the major frustrations that I have faced when working on projects which had poorly designed objects in them:
- When debugging code and seeing the object as a result of a complex operation, I canâ€™t really say who has changed the object, how many times, and if all of them did it correctly. Objectâ€™s state feels simply obscured, even if itâ€™s not, because I can see that the object can be modified by anything, including my code, including anything before my code, and including anything after my code. Any code I write can change anything it has, and has no control over what will be the final result after the object reaches the end of such â€œsmartâ€ classes pipeline. And I ask myself a question - why am I given a sward when I needed a screwdriver? (my code is a sward because it can chop this object into parts, and the object won't - or can't - even resist)
- When I want to understand all the flows in which the object participates, I have to literally read all the places where the object is being touched (even without modifications, because you can't say without checking), then narrow those places down to where the object is being manipulated at least in some way, and then consider all these together. This learning becomes even more complex when I realize that couple of code blocks are forming a flow or pipeline, so those should be learned together in combination (and few others also form yet another combination), because they together compose the operation that gives the object a final, consistent state. Anywhere in the middle, the objectâ€™s state is incorrect (or who knows what?), so God help me not to miss anything from the big picture. At such times, I become a bit stressed with the amount of information that I need to keep in mind at the same time while learning the code â€“ after all, brain is a limited size dynamic memory which cannot hold more than very few items at the same time. And here you go - learning has just become frustration as opposed to being fun.
- When I decide to implement a new requirement, Iâ€™m not sure where I need to put a new code that is about to manipulate given object. Not that there is no right place for it, instead any place works, so there are too many suitable places. And which one is right then? Iâ€™m also worried because I may miss something that can be affected, because my code is going to change the same object that the other part of the code may be expecting (I'm only creating or modifying a circle in the long chain) â€“ and what if I change it so that the other part of the code complains and breaks? Or what if I change it and it gets overwritten? How many other â€œsmartâ€ classes do I need to recheck? And I start having nightmaresâ€¦
One clear example that I recently encountered was something called â€œController â€“ Manager â€“ Repositoryâ€ pattern (and by "pattern" I mean anti-pattern). Repository calls external services and returns resulting objects, Manager takes these objects and can modify few properties of those, then returns them back to Controller; Controller can do the same as Manager â€“ modify few other properties and return them back. This can be seen as a set of â€œrefinersâ€ (I know, fancy word maybe, but an anti-pattern here!) stacked up on top of each other for the single type of object, doing all sorts of things to the object they get. But then, where do you put a code to change one more property? How do you categorize tasks performed by these 3 â€œsmartâ€ classes from each other? All right, you can come up with responsibilities and describe them on the paper, but how do you enforce them in the code? Do you expect everybody to follow your writings? Besides, there are more important questions â€“ imagine Iâ€™ve received this object from Controller, but it has few properties with incorrect values, where should I look into to investigate? is there a way to understand the flow without debugging the whole codebase? Who is responsible for other properties, and which ones specifically? How many times did each property change before getting into my hands? Was anything overwritten on the way to me? if so, why?
When all these questions arise, it should be clear to you that this and all other similar designs are confusing and absolutely not the right thing to do, so you still have work to do.
Note: Just for reference, this approach is officially an anti-pattern, and is referred to as "anemic domain model" by many authors. However, since I've promised to keep away from patterns and their names, I will just continue the way I started (for your own sake, because this recommendation is relevant regardless you "follow" the patterns or not).
Do you understand the issues Iâ€™ve described above? have you felt these frustrations too? If so, thatâ€™s already a step forward. Now, do you want to solve them too? Then read on.
Iâ€™ve split the solution into sub-sections so that you can grasp the concept step by step.
Business Objects vs. Anything Else
Letâ€™s start with foundational concepts. Any business object you write in your code should fulfill these expectations:
- Business objects are of limited purpose (not solving problems of the whole world, not a Swiss knife).
- Business objects are domain focused (objects represent concepts within the business problem, their properties represent the characteristics and state of the business concepts, and their methods represent the processes that involve one or more business concepts and query or alter their characteristics and state).
Above definitions sound simple and straightforward, so simple that many people simply overlook them. Iâ€™d suggest that you read them again, and then continue to the next section below.
Business objects vs. DTOs
First, letâ€™s distinguish these two beasts from each other.
I often ask this question during a technical interview for the engineering candidates: â€œwhatâ€™s the difference between business objects and DTOs?â€ and very often I hear answers like
- â€œbusiness objects are for business layer usage, while DTOs are for DTO layer usageâ€,
- â€œbusiness objects hold business data, while DTOs hold the data that we can send over the wireâ€,
- And so on.
It does not go too far until I ask a strict question: â€œso by looking at the class in the code, how can I say if itâ€™s business object or DTO?â€ or â€œwhat are the design guidelines for business objects against DTOs? Hint - they are not the sameâ€. And this is where almost all candidates (even senior ones) get stuckâ€¦ frustrating. But at least I understand who writes the software which scares me to death.
So, let me give you the main difference, so that you donâ€™t get stuck on interviews with people like me again:
Business objects represent business entityâ€™s state and behavior, while DTOs are just package of data. It goes even further â€“ business objects enforce constraints (have implementation code in them) which help them stay always consistent, at any point in time, while DTOs are open for manipulations and free changes (they are just property bags).
In other words, business object is the single source of truth about itself, anytime you look at it. You can't usually say the same about DTOs.
Above statements are crucially important, and should be used when trying to distinguish what is business object and what is not.
Since weâ€™re talking specifically about DTOs, they are not business objects because they donâ€™t have constraints. In other words, if you have a DTO, you can put any kind of data in it, and it wonâ€™t complain, wonâ€™t throw an exception, and can be sent to anybody without worrying that thereâ€™s something wrong with it. At any point in time, when you receive a DTO (e.g. through the wire), you cannot be sure that itâ€™s correct and consistent, because you know it can be modified by anybody else or by yourself, without much thinking whether the data in it is correct based on any business rules. Donâ€™t even bother to have â€œvalidatorâ€ (or any other fancy mechanism) in your code which puts "only" validated data into the DTO - that does not make the DTO consistent, because nothing forces the producer of a DTO to use your validator, because DTO can be constructed and modified without your validator too â€“ thatâ€™s it, itâ€™s not consistent.
Now that we are clear that there is a difference between DTOs and business objects, letâ€™s see how exactly we should design and implement business objects. Basically, let's see what goes into business objects that does not go into DTOs.
If you follow these design guidelines, you will be able to avoid all the issues described above. These guidelines are just step by step implementation of the business objectâ€™s definition statements which we already mentioned above at a higher level.
Business Object Design Rules (distilled)
Rules for designing business objects are simple to say, but can be a bit challenging to implement, especially if you are used to designing them poorly. I will go through the rules and will provide you some guidelines on how to specifically implement them in real life.
Rule #1 â€“ Encapsulate state
State means objectâ€™s fields. To encapsulate it, Business objects should be mostly read-only classes, and that does not mean immutable necessarily. Read-only means that the class appears to be read-only when we look at it from the outside. To achieve this, make all fields private, and avoid exposing writable properties which do nothing other than writing to the field (no cheating!).
When done with this step, your fields (your objectâ€™s state) should already feel much more secured than before.
Rule #2 â€“ Encapsulate behavior
Behavior is how the state can mutate (change). Obviously, if the fields are going to be private, we need to expose a way to change them, which means to change the state. For this purpose, a Business Object should expose methods (behavior) that change the state, and these methods should be the only way to change the state.
Inside such methods, we will have several things happening â€“ validation of the input data (method parameters), enforcement of the constraints (method parameters - even valid values - should not put the object in the incorrect state), other routine calls, dispatching events (I will discuss this part below in more details), and finally changing the actual state (fields). Basically, method is ensuring that the business objectâ€™s state transitions from the current correct state to the next correct state, and nothing else.
Assigning of a property (through the writable property) is fine in rare cases, when itâ€™s guaranteed that the assignment keeps the state in consistency. In other words, if changing a field associated with the property can be done in isolation, and if this always results in the correct state of the object (as a whole), then itâ€™s reasonable to have such property exposed as writable; otherwise, this field should be changed as part of the method implementation, together with other fields, whatever makes sense in combination, from business requirements standpoint. e.g. if you have fields for the Project object's start date, duration, and end date, duration and end date should be changed only together, otherwise object can be put into an invalid state by changing only one of these without the other (if duration changes, end date should be recalculated at the same time). Because of this, you can't just have writable properties for these two fields (thus allowing assignment to one without the other). Instead, it's better to have a method (e.g. SetDuration) which takes duration, and then calculates the project's end date accordingly before it returns. Thus, object moves from one correct state into another correct state - exactly as expected.
Rule #3 â€“ State Transition Behavior is Atomic and Consistent
This one is easy, and the above sections already covered big part of it. Basically, you need to envision your object between method calls, where itâ€™s always in the correct state. Method call moves your object from one correct state into another correct state.
Eventually, every method has logic that somehow changes the state, but only so that at the end of this operation, the state is correct again. This is achieved by all the instruments already mentioned: input validation, domain logic encapsulation into the method, constraints, and so on. Just donâ€™t let your method make the state inconsistent. And since the methods are the only way to manipulate the state, then you have already ensured that the objectâ€™s state can never be incorrect, as long as its own methods donâ€™t corrupt it.
Point of this section is that you still need to do the thinking, but that effort goes toward defining methods that change fields (state).
Rule #4 â€“ Dispatch Business Events from Business Objects
Above I mentioned that events should be dispatched by the business objects. I meant events that describe some specific situation that the business is interested in. Iâ€™ve heard many arguments against business objects dispatching events, which is just a result of the confusion or not completely understanding what an event is.
Many people describe an event as â€œwhen something happensâ€, which can be interpreted as â€œwhen something happens anywhere in the systemâ€. However, letâ€™s rethink this statement â€“ what can happen in the business-oriented software system? Answer is â€“ only a state change of a business object, and nothing else.
For example, let's imagine couple of different situations ("something happened"), and see how they translate into events:
- Was an email sent? That means state of the Message has changed from â€œReadyToSendâ€ to â€œSentâ€.
- Was the file downloaded? That means new DownloadEntry was added to the File object (effectively changing state of a File).
So, in short, anything that happens in a business software system, is a result of the business object changing its state. If the event needs to be fired, but nothing was changed prior to this, it just means that thereâ€™s something wrong with the business objectâ€™s design. Any change which results in an event, should be expressed as a state change.
Alright, now that we've decided that every event is a result of the business objectâ€™s state change, then next question is â€“ how do we fire the event to the rest of the world?
If you recall, business objectâ€™s method is responsible to change the state, and nothing else has this capability. So, itâ€™s obvious that the method itself can fire the event when the state was changed, because thatâ€™s the only place where we can guarantee the state was changed. If you are firing an event about a state change of the object from outside of this object, then your code is lying to the rest of the system that something was changed. Code that fires events on behalf of some other objects, is brittle and tightly coupled to those other objects. Start firing events from where the state is really changing, otherwise the state might stop changing (somebody changed the source object), but your code will continue firing this event (somebody forgot to change your code too, because it was not in the same place where the state was changing).
Rule #5 â€“ No â€œSmartâ€ Classes
No more special classes that can change business objectâ€™s state without asking business object to do so.
As Iâ€™ve described above, traditional and completely incorrect approach is to have many â€œsmartâ€ classes (e.g. Controllers, Managers, Repositories, etc.), each of them carrying on a different kind of business operation, while also directly manipulating states of the business objects. You might be used to this approach, and I encourage you to stop doing itâ€¦ but I donâ€™t need to try too hard. If you follow all the above guidelines, you wonâ€™t be able to design such special classes anymore, because your business objects wonâ€™t allow direct manipulations from the outside, as opposed to DTOs for instance.
So, this guideline is really just a consequence â€“ you get it for free if you follow the previous guidelines.
One last thing to mention is, these "smart" classes used to hold all the business logic before. With the right approach, business logic will be expressed where it's supposed to be - inside business objects. And this is an important and valuable change: remember that business objects are the house of the business logic, they are the owners of their own state, and they are the source of the business (domain) events. Centralizing all these concepts into business objects makes it much easier to understand how the system functions - everything's built around business objects.
Rule #6 - Repositories Persist and Provide Business Objects
Now that weâ€™ve agreed that business objects manage their own state, natural question comes to mind â€“ where do they originate from with that state which is always correct? Where is that magic hole?
Thatâ€™s where repositories come into picture â€“ they give you the business objects with the state that they had when they were last persisted. And since the persistence part is also controlled by the same repositories, itâ€™s never a problem for the repository to give you back exactly what you gave to it once - an object with the correct state.
In other words, your repositories should be able to load and save business objects, from whichever specific storage you want, without losing or corrupting their state between saves and loads.
And since Iâ€™ve touched repositories, you will (and should) start thinking about things that are happening inside repositories â€“ retrieving data from some kind of storage (e.g. database table rows), then mapping it to the business objects, and then returning resulting business objects backâ€¦ wait, did you say â€œmappingâ€œ? Did things like â€œautomapperâ€ come to mind? but how would you map from the database rows (which are almost like DTOs â€“ with all properties supporting reads and writes) into business objects when these business objects wonâ€™t anymore expose the writable properties (based on the above guidelines)?
And this brings up next guideline.
Rule #7 â€“ Automatic Mapping Frameworks are NOT for Business Objects
Period. These frameworks have a great purpose to map from simple objects to other simple objects as long as the property names match and all the target properties are writable, but donâ€™t take it too far - our business objects are not going to expose writable properties as we've already agreed.
Iâ€™ve seen incorrectly designed business objects that are suitable for automapper mappings (i.e. with all writable properties), but that smells like fitting your design under frameworks, rather than using the correct tools for the job. If you go with all writable properties, then how do you ensure all the goodness weâ€™ve discussed above? â€“ consistency, state encapsulation, no â€œsmartâ€ objectsâ€¦ Stop the madness, keep the design right, and then only choose the right framework to accomplish what you want.
In other words, I will not say that automapper and other similar frameworks encourage you to design your business objects incorrectly; instead, they donâ€™t mention where they should not be used (not their problem, yours!).
So, use automatic mapping frameworks (such as automapper) with great caution. Specifically, don't design your business objects poorly just because you want to automatically map property values - you're compromising too much for a minor convenience.
I guess Iâ€™ve covered it all.
If you just try and implement your software with all the guidelines I mentioned, you will feel relieved when learning it, debugging it, or adding new functionalities to it. It just becomes very simple:
- If you want to learn how the object is being manipulated, just go through the object itself, and read the methods. All they are at one place. Business Objects have become the centralized source of business knowledge - no need to guess where to look for it.
- If you want to debug the software, donâ€™t anticipate awkward behavior such as object being changed while passed through the pipeline of the â€œsmartâ€ classes. Any change to the object is happening only though the methods of this same object, so no need to scan all the places and remember everything at once. Debugging has just become easier too (if at all necessary).
- If you want to add a new capability that changes the given business object, just follow the same pattern â€“ add method to the business object itself that changes the state. No need to think where this code needs to be, because thereâ€™s only one right place for it â€“ the business object itself.
Oh, and by the way, donâ€™t think that Iâ€™m a dreamer, because this is exactly how I implement my code at all times, so Iâ€™ve tried it myself many times already. Every time I write software, I enjoy it because of the approach described above, and all the benefits it gives me back.
Unfortunately, I have also tasted the incorrect designs too, when working with teams that had already implemented it poorly - so it was too late in the game to redesign everything they had "invented". But I hope those teams will change their minds by discovering and reading papers like this.
Obviously, you can use better terms for things Iâ€™ve written here (specifically if you are fond of DDD, or design patterns, or many other software theories and practices), but I kept it mostly unrelated to those, because these recommendations should not be taken as part of other guidelines or standards necessarily.
Nothing here conflicts with any other patterns, paradigms, frameworks, or approaches that I know and follow, or respect and believe in.