In this blog post I outline my thinking on sharing code that deals with different types of Entities in your domain. We\u2019ll cover what Entities are, code reuse strategies, pitfalls such as Shotgun Surgery and Anemic Domain Models and finally Bounded Contexts.<\/p>\n
I work at Wikimedia Deutschland<\/a>, where amongst other things, we are working on a software called Wikibase<\/a>, which is what powers the Wikidata<\/a> project. We have a dedicated team for this software, called the Wikidata team, which I am not part of. As an outsider that is somewhat familiar with the Wikibase codebase, I came across a writeup of a perceived problem in this codebase and a pair of possible solutions. I happen to disagree with what the actual problem is, and as a consequence also the solutions. Since explaining why I think that takes a lot of general (non-Wikibase specific) explanation, I decided to write a blog post.<\/p>\n Let\u2019s start with defining what an Entity is. Entities are a tactical Domain Driven Design<\/a> pattern. They are things that can change over time and are compared by identity rather than by value, unlike Value Objects, which do not have an identity.<\/p>\n Wikibase has objects which are conceptually such Entities, though are implemented \u2026 oddly from a DDD perspective. In the above excerpt, the word entity, is confusingly, not referring to the DDD concept. Instead, the Wikibase domain has a concept called Entity, implemented by an abstract class with the same name, and derived from by specific types of Entities, i.e. Item and Property. Those are the objects that are conceptually DDD Entities, yet diverge from what a DDD Entity looks like.<\/p>\n Entities normally contain domain logic (the lack of this is called an Anemic Domain Model<\/a>), and don\u2019t have setters. The lack of setters does not mean they are immutable, it\u2019s just that actions are performed through methods in the domain language (see Ubiquitous Language<\/a>). For instance \u201cconfirmBooked()\u201d and \u201ccancel()\u201d instead of \u201csetStatus()\u201d.<\/p>\n What follows is an excerpt from a document aimed at figuring out how to best construct entities in Wikibase:<\/p>\n Some entity types have required fields:<\/p>\n The ID field is required by all entities. This is less problematic however, since the ID can be constructed and treated the same way for all kinds of entities. Furthermore, the ID can never change, while other required fields could be modified by an edit (even a property\u2019s data type can be changed using a maintenance script).<\/p>\n The fact that Properties require the data type ID to be provided to the constructor is problematic in the current code, as evidenced in EditEntity::clearEntity:<\/i><\/p>\n …as well as in EditEntity::modifyEntity():<\/p>\n Such special case handling will not be possible for entity types defined in extensions.<\/p>\n<\/div>\n It is very natural for (DDD) Entities to have required fields. That is not a problem in itself. For examples you can look at our Fundraising software<\/a>.<\/p>\n So what is the problem really?<\/p>\n Normally when you have a (DDD) Entity, say a If the code handling This sharing via composition is not really visible \u201cfrom outside\u201d of the involved services, except for the code that constructs them. If you have a In the Wikibase codebase there is an attempt at code reuse by having services that can deal with all types of Entities. Phrased like this it sounds nice. From the perspective of the user of the service, things are great at first glance. Thing is, those services then are forced to actually deal with all types of Entities, which almost guarantees greater complexity than having dedicated services that focus on a single entity.<\/p>\n If your In those cases the service can add a bunch of \u201cif has method The \u201cif This delegation approach is sane enough from a OO perspective. It does however involve specific repositories, which begs the question of why you are creating a general one in the first place. If there is no compelling reason to create the general one, just stick to specific ones and save yourself all this not needed complexity and vagueness.<\/p>\n In Wikibase there is a generic web API endpoint for creating new entities. The users provide a pile of information via JSON or a bunch of parameters, which includes the type of Entity they are trying to create. If you have this type of functionality, you are forced to deal with this in some way, and probably want to go with the delegation approach. To me having such an API endpoint is very questionable, with dedicated endpoints being the simpler solution for everyone involved.<\/p>\n To wrap this up: dedicated entity handling code is much simpler than generic code, making it easier to write, use, understand and modify. Code reuse, where warranted, is possible via composition inside of implementations without changing the interfaces of services. Generic entity handling code is almost always a bad choice.<\/p>\n On top of what I already outlined, there is another big issue you can run into when creating generic entity handling code like is done in Wikibase.<\/p>\n Bounded Contexts<\/a> are a key strategic concept from Domain Driven Design. They are key in the sense that if you don\u2019t apply them in your project, you cannot effectively apply tactical patterns such as Entities and Value Objects, and are not really doing DDD at all.<\/p>\n \u201cStrategy without tactics is the slowest route to victory. Tactics without strategy are the noise before defeat.\u201d — Sun Tzu<\/p><\/blockquote>\n Bounded Contexts allow you to segregate your domain models, ideally having a Bounded Context per subdomain. A detailed explanation and motivation of this pattern is out of scope for this post, but suffice to say is that Bounded Contexts allow for simplification and thus make it easier to write and maintain code. For more information, I can recommend Domain-Driven Design Destilled<\/a>.<\/p>\n In case of Wikibase there are likely a dozen or so relevant subdomains. While I did not do the analysis to create a comprehensive picture of which subdomains there are, which types they have, and which Bounded Contexts would make sense, a few easily stand out.<\/p>\nDDD Entities<\/h3>\n
The perceived problem<\/h3>\n
\n
\/\/ FIXME how to avoid special case handling here?\nif ( $entity instanceof Property ) {\n \/** @var Property $newEntity *\/\n $newEntity->setDataTypeId( $entity->getDataTypeId() );\n}\n<\/pre>\n\/\/ if we create a new property, make sure we set the datatype\nif ( !$exists && $entity instanceof Property ) {\n if ( !isset( $data['datatype'] ) ) {\n $this->errorReporter->dieError( 'No datatype given', 'param-illegal' );\n } elseif ( !in_array( $data['datatype'], $this->propertyDataTypes ) ) {\n $this->errorReporter->dieError( 'Invalid datatype given', 'param-illegal' );\n } else {\n $entity->setDataTypeId( $data['datatype'] );\n }\n}<\/pre>\nGeneric vs specific entity handling code<\/h3>\n
Donation<\/code>, you also have dedicated code that deals with those Donation<\/code> objects. If you have another entity, say MembershipApplication<\/code>, you will have other code that deals with it.<\/p>\nDonation<\/code> and the code handing MembershipApplication<\/code> is very similar, there might<\/em> be an opportunity to share things via composition. One should be very careful to not do this for things that happen to be the same but are conceptually different, and might thus change differently in the future. It\u2019s very easy to add a lot of complexity and coupling by extracting small bits of what would otherwise be two sets of simple and easy to maintain code. This is a topic worthy of its own blog post, and indeed, I might publish one titled The Fallacy of DRY<\/a> in the near future.<\/p>\nDonationRepository<\/code> and a MembershipRepository<\/code> interface, they will look the same if their implementations share something, or not. Repositories might share cross-cutting concerns such as logging. Logging is not something you want to do in your repository implementations themselves, but you can easily create simple logging decorators<\/a>. A LoggingDonationRepostory<\/code> and LoggingMembershipRepository<\/code> could both depend on the same Logger<\/code> class (or interface more likely), and thus be sharing code via composition. In the end, the DonationRepository<\/code> still just deals with Donation<\/code> objects, the MembershipRepository<\/code> still just deals with Membership<\/code> objects, and both remain completely decoupled from each other.<\/p>\nDonation<\/code> and MembershipApplication<\/code> entities both implement Foobarable<\/code> and you have a FoobarExecution<\/code> service that operates on Foobarable<\/code> instances, that is entirely fine. Things get dodgy when your Entities don\u2019t always share the things your service needs, and the service ends up getting instances of object, or perhaps some minimal EntityInterface<\/code> type.<\/p>\ndoFoobar<\/code>, call it with these arguments\u201d logic. Or perhaps you\u2019re checking against an interface instead of method, though this is by and large the same. This approach leads to Shotgun Surgery<\/a>. It is particularly bad if you have a general service. If your service is really only about the doFoobar<\/code> method, then at least you won\u2019t need to poke at it when a new Entity is added to the system that has nothing to do with the Foobar concept. If the service on the other hands needs to fully save something or send an email with a summary of the data, each new Entity type will force you to change your service.<\/p>\ndoFoobar<\/code> exists\u201d approach does not work if you want plugins to your system to be able to use your generic services with their own types of Entities. To enable that, and avoid the Shotgun Surgery, your general service can delegate to specific ones. For instance, you can have an EntityRepository<\/code> service with a save method that takes an EntityInterface<\/code>. In it\u2019s constructor it would take an array of specific repositories, i.e. a DonationRepository<\/code> and a MembershipRepository<\/code>. In its save method it would loop through these specific repositories and somehow determine which one to use. Perhaps they would have a canHandle<\/code> method that takes an EntityInterface<\/code>, or perhaps EntityInterface<\/code> has a getType<\/code> method that returns a string that is also used as keys in the array of specific repositories. Once the right one is found, the EntitiyInterface<\/code> instance is handed over to its save method.<\/p>\ninterface Repository {\n public function save( EntityInterface $entity );\n public function canHandle( EntityInterface $entity ): bool;\n}\n\nclass DonationRepository implements Repository { \/**\/ }\nclass MembershipRepository implements Repository { \/**\/ }\n\nclass GenericEntityRepository {\n \/**\n * @var Repository[] $repositories\n *\/\n public function __construct( array $repositories ) {\n $this->repositories = $repositories;\n }\n\n public function save( EntityInterface $entity ) {\n foreach ( $this->repositories as $repository ) {\n if ( $repository->canHandle( $entity ) ) {\n $repository->save( $entity );\n break;\n }\n }\n }\n}<\/pre>\nBounded Contexts<\/h3>\n