DEV Community: Ahmed Shirin

One Team - One Language

Ahmed Shirin — Thu, 06 Dec 2018 22:33:28 +0000

Don't we all just love the Grammar Police? You spend a considerate amount of time and effort expressing some opinion of yours on the internet, yet this teeny tiny grammatical error slips from your hands and BAM! Now your entire argument is deemed invalid and you're doomed to eternity for committing such an unforgivable abomination. Shame...

Internet trolls aside...When speaking in the context of software development, one aspect is usually taken for granted, that is the eloquence and fluency of the domain specific language shared by the team. It doesn't matter if you're using English, Spanish, German or even Dothraki as long as the team is committed to using a single, unified set of terms to express their domain. Yet unfortunately, several teams seem to be very tolerant when it comes to ambiguity in their language.

A World of Dialects

Over the years, humans have managed to scatter themselves across disparate parts of the globe to form communities that evolved their own unique languages as a means of communication. Some of these languages have even evolved into different dialects that might sound highly dissimilar, which is why a US English speaker is likely to have a tough time understanding an Australian accent. In the world of software development, we can say that the same situation applies; different enterprises working in similar domains are likely to use different languages amongst them, for example in the healthcare domain, one enterprise might use "Medical Practitioner" to describe their service providers while another might simply use the term "Doctor". No rules govern the choice of one term over the other, yet the organization must aggressively enforce its own language - the Ubiquitous Language - across the entire team and refrain from allowing foreign terminology from leaking into the ranks.

In large organizations, it is pretty normal to encounter various dialects of the same language used by teams working in different contexts, for example, in a fictional e-Commerce business, the term “Order” might be used by the Purchases team to represent a request made by a Customer to buy a set of products from the website’s inventory, while the Shipping team will use the same term “Order” to represent a request sent to one of the Couriers to ship Cargo from a Warehouse located in one Zone to another. This is fine as long as each team unanimously agrees to their own definition of an “Order”.

When a rogue subset of a single team starts using its own jargon in communication with others (one prominent case is developers and business experts using different terminology in meetings), confusion will emerge and the presence of translators who understand both dialects will be necessary to bridge the gap between the team members, putting the team at risk of mistranslation as well as an unnecessary delay and inefficiency due to the newly introduced bottleneck. Moreover, from a technical point of view, it is highly likely to encounter crazy code like this: (assume a reservation context)

class ReservationService
{
    void CreateReservation()
    {
       Appointment appointment = _appointmentFactory.CreateAppointment(...);
       //It is a Reservation, but Randy likes to think of it more as an Appointment ¯\_(ツ)_/¯
    }
}

Contradictions and ambiguities in the language offer an opportunity for the team to learn more about the domain and build a deeper model. Team members should be very wary of such ambiguities and address them as soon as possible, one particular case I've came across recently while working on the Product Catalog for an e-Commerce application is that we used the terms "Vendor" and "Brand" interchangeably to denote the entities supplying our products. The team understood the importance of having a unified language and thus we discussed this confusion where good arguments were placed in favor of using either terms and at the end it was decided to use the term "Brand" in context of the Product Catalog until further insight emerges which warrants reverting back to "Vendor" or using a completely new term.

Polysemous Integration

All is well until integration between teams starts looming around. Earlier we demonstrated an example of the "Order" polyseme being used differently in Purchases and Shipping. So when these two teams start the integration process, how should contradictions be managed? Is the Shipping team’s definition of “Order” more valid than the Purchases team’s (or vice versa)? Definitely not, after all - conceptually - both of them are Orders. Should management attempt to force the two teams to completely abandon the term “Order” in favor of adopting “Purchase Order” and “Shipping Order” instead? Not a good idea and probably wouldn’t work anyway, because from the Purchases team’s point of view, an “Order” is a term that represents a single unambiguous concept in their domain and since they probably have no dependency on the concept of a Shipping Courier, therefore why would they need to distinguish their “Order” by prefixing it with the word “Purchase”?

The situation gets more complicated if the integrating teams have to share parts of their model, which necessitates a linguistic breakthrough to come up with a more mature set of vocabulary that serves both groups conveniently. However, if that's not the case, then it is best for each team to hold onto its unified vocabulary within its context, while the team members responsible for the integration process should perfect the different dialects and how to translate between them.

Beware the False Cognates

Wikipedia defines False Cognates as follows:

False cognates are pairs of words that seem to be cognates because of similar sounds and meaning, but have different etymologies.

An example of False Cognates is the Spanish word "Ropa" which could be easily confused with the English word "Rope", yet "Ropa" in Spanish means "Clothes" while the accurate Spanish equivalent of the English word "Rope" would be "Cuerda".

One particularly dangerous situation is when different members of a software team are using the same term believing it implies the same meaning then discover at a later stage that this was not the case. An example would be in a Ride Sharing application where the team uses the term "Trip" to denote their regular rides operated by their own drivers. So when they started building a new feature for supporting rides operated by Taxi/Cab drivers, the business analysts were still using the same term "Trip" for the Taxi rides, which lead the development team to - incorrectly - assume that they could reuse their "Trip" model in the new feature, however, since the team had no process of Continuous Integration, it was discovered post production that the "Trip" model held subtle assumptions which rendered it unsuitable for reuse in the new feature. Oops...

Conclusion

When it comes to the Ubiquitous Language, you have the green light to be as strict as possible to maintain its integrity. Exercise the language relentlessly and always be on the watch for any signs of confusion.

The Anti-Corruption Layer Pattern

Ahmed Shirin — Sun, 11 Nov 2018 10:05:42 +0000

It is no secret that integrating with legacy systems is a no fun milestone. Poor documentation, lack of support, messy interfaces and more than a handful of dormant bugs are just a subset of the problems you might face in the integration process. Yet more than often, integration is an absolute necessity for technical and/or political reasons. Integration with legacy systems imposes a risk on the system under design since legacy models are usually poorly designed and thus your new, well designed model is very likely to be corrupted by the legacy integration.

Integration Strategies:

Developers who need to work with legacy systems are faced with four choices:

1- Ditch the legacy: Having a common use case isn't always a justification for integration. Developers should consider this option by scrutinizing the value of the legacy system and weighing it in against the cost of integration.

2- Conform to the legacy: When the organization has no plans to replace the legacy system, and when the quality of the legacy model is acceptable enough, then diligently conforming to the legacy model would eliminate all integration costs. A conformist approach must be seriously considered in situations where peripheral extensions are being added to a well established, dominant legacy system. This choice is highly underrated due to our irresistible infatuation with re-inventing the wheel and wasting time and money working out solutions that deliver little to no business value.

3- Anti-Corruption Layer: A highly defensive strategy to isolate your model from corruption by legacy models.

4- Replacing the Legacy: The least favorable option. Developers should refrain from phasing out large and complex models of a legacy system (specially when these models belong to the system's Core Domain) while working simultaneously on the new model, as these ambitious attempts are more susceptible to undesired outcomes.

Before attempting an Anti-Corruption Layer solution, you should carefully rethink options 1 and 2; Anti-Corruption layers can get very ugly and complicated in addition to the fact that they compose new elements to be added to the organization's context map that require maintenance and support. Before approaching the Anti-Corruption Layer pattern let's talk briefly about two prominent design patterns:

Façade:

A Façade is a pattern that is used to provide a simpler interface to a complex system. The Façade should adhere to the interfaced system's model and refrain from introducing a new model of its own (i.e: They should speak the same language).

Think of a trip planning system that has the following interface:



public interface ITripService
{
    void BookAirline();
    void ReserveHotelRoom();
    void ReserveTouristAttractionTickets();
}

A simpler interface could be provided -when needed- through the following Façade which co-ordinates the execution of the entire operation:



public interface ITripServiceFacade
{
    void PlanItinerary();
}

Adapter:

A Wall Adapter

An Adapter is a pattern which allows communication between two incompatible abstractions by providing an interface that the client can make sense of. The adapter is allowed to speak the language of the client and adapt it to the other sub-system.

Think of a ride hailing application having the following interface:



public interface ITransportationService
{
    void StartTrip(string country, Zipcode from, Zipcode to);
}

However, when insight emerged that - in some countries - trips should be fared based on the exact co-ordinates of the source and destination locations instead of zipcodes, an Adapter was provided:



public interface ITransportationServiceAdapter
{
    void StartTrip(Coordinates from, Coordinates to);
}

Notice that the Adapter speaks the language of the client and is responsible for initiating the corresponding request to the adaptee.

Anti-Corruption Layer:

The Great Fire engulfing the city of Rome

An Anti-Corruption Layer combines a set of Façades, Adapters and Translators to isolate a model from corruption by other models it needs to integrate with. The Anti-Corruption Layer might be uni-directional in case of the existence of a Customer-Supplier relationship between the two models or bi-directional otherwise.

To illustrate the pattern, let's first consider an e-Commerce application that displays an order's shipping costs by estimating the number and dimensions of the packages required to ship the order then uses a complex network traversal algorithm to find the cheapest route for shipping. From this we can quickly deduce two distinct contexts: Shipping and Packaging, each with different capabilities and a completely independent model.

Turns out that the organization already owns a legacy Packaging service that has been used for years - since the organization has previously specialized in the packaging industry before shifting the strategy towards e-Commerce. As the architects closely examined the legacy Packaging service, they realized that integration with the legacy is inevitable since the service is highly complicated (indicating that a-lot of knowledge has been crunched into the legacy) and therefore abandoning the legacy or attempting a large scale replacement are unwieldy solutions. A closer examination also ruled out a conformist approach since the legacy model is very outdated and made assumptions that do not fit anymore into the current business model, therefore conforming the Shipping context to the legacy Packaging model would cause a high rate of corruption on the Shipping side.

Unfortunately, the Packaging service is too old, undocumented, and is notorious for a number of bugs that forced several ad hoc workarounds across other components in the system, moreover, the original developers who wrote the service have departed from the organization leaving the Shipping team completely on its own. At this point, the architects decided that the Shipping context should be integrated with the Packaging context with an Anti-Corruption layer isolating the Shipping model from the legacy.

Let's take a closer look to the legacy Packaging model to highlight the model weaknesses and how they can corrupt the Shipping model:



namespace Warehouse.Packaging 
{
    public class Container 
    { 
        //Irrelevant details
    }

    public class Package 
    { 
        public double LengthInInches { get; }
        public double WidthInInches { get; }
        public double HeightInInches { get; }
    }

    public class Item 
    {
        public double LengthInInches { get; }
        public double WidthInInches { get; }
        public double HeightInInches { get; }
    }

    public class Warehouse 
    {
        public string Code { get; }
        public string ZipCode { get; }
        public IEnumerable<Container> AvailableContainers { get; }
        //Further details of a messy model
    }

    public interface ILegacyPackagingService 
    {
        bool ValidateItemDimensions (IEnumerable<Item> items);
        IEnumerable<Package> PackageItems (IEnumerable<Item> items, Warehouse warehouse);
        IEnumerable<Package> OptimizePackaging (IEnumerable<Package> packages);
    }
}

Several problems exist in the above domain model:

1- The ILegacyPackagingService offers a complex interface where Validation, Packaging and Optimization are provided as three separate APIs - for a good reason probably - however this doesn't fit well with the Shipping model's needs since all of these operations are viewed as a single operation from the Shipping's point of view.

2- The Item and Package models use the Imperial System of measurement which presents a conflict with a new organization-wide policy to adopt the metric system in all new models.

3- The Warehouse model in the Packaging module is highly outdated and no longer reflects how the business models its own Warehouses.

4- The PackageItems API defined in the ILegacyPackagingService introduces a coupling between the Packaging logic and the Warehouse model - since packaging was previously viewed as an operation that can only take place within one of the organization's designated warehouses. However, the current Shipping model cannot sustain such an assumption since it allows products to be shipped directly from the external Vendors' storage facilities.

Obviously, the Anti-Corruption Layer has a-lot of work to do. Allowing any of the above mentioned problems to leak into the Shipping model would yield a corrupted model that carries all the weaknesses of the legacy system. To mitigate the first issue, we introduce a Façade within the Anti-Corruption Layer:



namespace Warehouse.Packaging.AntiCorruption.Shipping 
{
    public interface IPackagingServiceFacade 
    {
        IEnumerable<Warehouse.Packaging.Package> PackageItems (IEnumerable<Item> items, Warehouse warehouse);
    }

    public class PackagingServiceFacade : IPackagingServiceFacade 
    {
        private readonly ILegacyPackagingService _packagingService;

        public PackagingServiceFacade (ILegacyPackagingService packagingService) 
        {
            _packagingService = packagingService;
        }

        public IEnumerable<Warehouse.Packaging.Package> PackageItems (IEnumerable<Item> items, Warehouse warehouse) 
        {
            if (_packagingService.ValidateItemDimensions (items)) 
            {
                var packages = _packagingService.PackageItems (items, warehouse);
                var optimizedPackages = _packagingService.OptimizePackaging (packages);
                return optimizedPackages;
            }

            return Enumerable.Empty<Package> ();
        }
    }
}

Note that the Façade uses the same model as the Packaging service, no model elements were added and the language is maintained. The Façade only offers a friendlier interface to the model. The Façade is even placed under the Warehouse.Packaging module/namespace which encompasses the Packaging context (Anti-Corruption layers can span multiple modules).

To account for the second problem, the Anti-Corruption layer will define a translator object to map between the different models used in the two contexts, in the following example we are using AutoMapper to illustrate the mapping operation in a simple manner:



namespace Logistics.Shipping.AntiCorruption.Packaging
{
    public class PackagerProfile : Profile
    {
        private const double InchesCmConversionConst = 0.39370;

        public PackagerProfile()
        {
            CreateMap<Product, Item>()
                .ForMember(dst => dst.LengthInInches, opt => opt.MapFrom(src => src.LengthInCm * InchesCmConversionConst))
                .ForMember(dst => dst.WidthInInches, opt => opt.MapFrom(src => src.WidthInCm * InchesCmConversionConst))
                .ForMember(dst => dst.HeightInInches, opt => opt.MapFrom(src => src.HeightInCm * InchesCmConversionConst));

            CreateMap<Warehouse.Packaging.Package, Logistics.Shipping.Package>()
                .ForMember(dst => dst.LengthInCm, opt => opt.MapFrom(src => src.LengthInInches / InchesCmConversionConst))
                .ForMember(dst => dst.WidthInCm, opt => opt.MapFrom(src => src.WidthInInches / InchesCmConversionConst))
                .ForMember(dst => dst.HeightInCm, opt => opt.MapFrom(src => src.HeightInInches / InchesCmConversionConst));
        }
    }
}

The translator can be used back and forth to map the incompatible models.

To handle the third and forth issues, we introduce an Adapter to the Anti-Corruption layer which provides the Shipping service with a more compatible interface that is loosely coupled from the Warehouse model and instead uses the Container value object to represent the packaging capabilities:



namespace Logistics.Shipping.AntiCorruption.Packaging
{
    public interface IPackagingService 
    {
        IEnumerable<Logistics.Shipping.Package> PackageItems (IEnumerable<Product> items, IEnumerable<Container> containers);
    }

    public class PackagingServiceAdapter : IPackagingService 
    {
        private readonly IPackagingServiceFacade _packagingServiceFacade;
        private readonly IMapper _mapper;

        public PackagingServiceAdapter (IPackagingServiceFacade packagingServiceFacade, IMapper mapper) 
        {
            _packagingServiceFacade = packagingServiceFacade;
            _mapper = mapper;
        }

        public IEnumerable<Logistics.Shipping.Package> PackageItems (IEnumerable<Product> products, IEnumerable<Container> containers) 
        {
            Warehouse warehouse; //Logic to initialize a transient dummy warehouse
            var items = _mapper.Map<IEnumerable<Item>> (products); //Using the translator to map the Product model to an Item
            var packages = _packagingServiceFacade.PackageItems (items, warehouse); //Calling the Façade 
            return _mapper.Map<IEnumerable<Logistics.Shipping.Package>> (packages); //Mapping the Packager's result to the Package model defined in the Shipping context
        }
    }
}

The outcome is a Shipping model that is integrated with the legacy Packaging service without being corrupted by the legacy:



namespace Logistics.Shipping 
{
    public class Zone 
    { 
    }

    public class Product 
    {
        public double LengthInCm { get; }
        public double WidthInCm { get; }
        public double HeightInCm { get; }
    }

    public class Package 
    {
        public double LengthInCm { get; }
        public double WidthInCm { get; }
        public double HeightInCm { get; }
    }

    public class Courier 
    {
        private IPackagingService _packagingService;

        public double GetQuote (IEnumerable<Product> items, Zone source, Zone destination) 
        {
            var packagingCapabilities = _capabilitiesService.GetPackagingCapabilities (source);
            var packages = _packagingService.PackageItems (items, packagingCapabilities.Containers);
            //Shipping specific logic goes here
        }
    }
}

A rough map of the domain model would be as follows:

Details concerning the Anti-Corruption layer are omitted for simplicity.

Conclusion

The Great Wall of China

Developing an Anti-Corruption layer is a time consuming process that requires lots of analysis and development work. Architects should not jump to this solution at once and instead consider other simple alternatives, however when there is no other choices, an Anti-Corruption layer - just like a wall surrounding a fortress from hostile invasion - will protect your model from outer influences and allow you to work in isolation.

The Flyweight Pattern and Value Objects

Ahmed Shirin — Sat, 29 Sep 2018 08:01:35 +0000

As software engineers and modelers, we usually come across different code design problems on a daily basis; most of these puzzles have already been solved and best practices have been laid to define a contract among developers detailing how these problems should be tackled. Out of the box solutions usually yield more complexity and a deviation from the norm, and that's why - in my opinion - I believe that deep knowledge of design patterns is an imperative factor affecting the quality of the team's codebase. However, knowledge of these patterns is just one half of the equation, the other half is being capable of choosing the appropriate situation to apply a design pattern solution, and being equally capable of spotting out when a pattern is being abused or when it just doesn't make sense at all.

One interesting Structural pattern is the Flyweight (Gamma et al, 1995). Often, developers face a situation where too many identical objects are being created; managing this process will define the difference between a stable system and an unusable one, and thats where the Flyweight comes to rescue.

But first of all, what does it mean for two objects to be identical?

Let's revisit an important distinction between two categories of objects in our models: Entities and Value Objects.

Conceptually, each human being is a separate "Entity" having their own identity and thread of continuity; a person can change their name, their hair color, their gender and their Nationality, yet their identity remains the same, implying that two persons having the exact same attributes/characteristics cannot be considered identical.

On the other hand, there exists several concepts in our perceivable world that lack an identity yet still they convey some meaning, a famous example is a one dollar bill; we don't really care which one dollar bill we possess as much as we care about its value (Value Object), and thus we would normally view all the one dollar bills as identical to each other.

When designing a model, the process of deciding whether an object (representing some concept in the domain sphere) possesses or lacks an identity is not a trivial issue and requires some understanding of the problem at hand, adding that it is highly likely that this decision could vary from one domain to the other.

Value Objects are more liberating than Entities, two Value Objects having the same attributes are considered identical, unlike Entities which require an identity based comparison mechanism. From this point, it is safe to state that Value Objects are interchangeable, meaning that multiple objects can reference/share an instance of a value object without leading to some conceptual dilemma. For example, a shipping application that doesn't need to uniquely identify each Vehicle in its fleet - implying that a Vehicle in this model is a Value Object - can safely create dozens of Shipments referencing a single instance of a Vehicle, when applicable.

As a corollary of the previous statement, Value Objects should be immutable; interchangeability implies that an operation having a side effect on an instance of the interchangeable object will result in a rippling effect across the system. Therefore, Commands applicable to a Value Object should be side effect free and return a new instance of the object instead of mutating it.

Conceptually, the immutability of Value Objects holds true, since a Value Object will always describe an observation of some concept in the universe. For example the color "Red" will always describe a distinct color having some observable characteristics. Adding the color "Green" to "Red" won't change the observable characteristics of the color "Red" but will instead yield a new color "Yellow" (This is analogous to a Command on a Value Object which returns a new instance of the object).

So back to the original problem where a system needs to manage the creation and existence of numerous identical objects. Logically, these objects should be Value Objects for a Flyweight Pattern refactoring to apply; the interchangeability of Value Objects allows developers to introduce an abstraction (Flyweight Factory) that is capable of reusing the set of preexisting objects (Flyweights) in order to get a reference to the object, while the immutability aspect of Value Objects allows clients to safely issue Commands on the Flyweights without worrying whether these Commands will have a side effect on the system.

So let's define the three main components of the pattern:

Flyweight: The Value Object to be interchanged within the system.
Flyweight Factory: An abstraction that is responsible for retrieving a Flyweight in an efficient manner.
The Client.

Assuming that we're working on a Shipping system that is cluttered with numerous Zone objects being assigned to different Shipping Routes. To apply a Flyweight Pattern refactoring, we first define the Zone as an immutable Value Object that will act as the Flyweight.

public class Zone : IEquatable<Zone>
//An immutable flyweight...This represents a domain value object
{
    public string ZipCode { get; }

    public IReadOnlyCollection<string> AvailableCouriers { get; private set; }

    public Zone (string zipCode) 
    {
        ZipCode = zipCode;
        AvailableCouriers = new List<string> ();
    }

    public Zone (string zipCode, IEnumerable<string> couriers) : this (zipCode) 
    {
        AvailableCouriers = new List<string> (couriers.Distinct ());
    }

    public Zone RegisterCourier (string courier) 
    {
        var newCouriers = new List<string> (AvailableCouriers) 
        {
            courier
        };

        return new Zone (ZipCode, newCouriers);
    }

    public bool Equals (Zone other) 
    {
        if (other == default (Zone))
            return false;

        if (ReferenceEquals (this, other))
            return true;

        if (!string.Equals (ZipCode, other.ZipCode, StringComparison.OrdinalIgnoreCase))
            return false;

        if (AvailableCouriers.Count != other.AvailableCouriers.Count)
            return false;

        if (!AvailableCouriers.All (x => other.AvailableCouriers.Contains (x)))
            return false;

        return true;
    }
}

We then introduce the ZoneFactory acting as the Flyweight Factory, a separate standalone Factory is justified in this case since the responsibility of managing the Flyweight collection doesn't belong to the Flyweight object. In this implementation, we are using a Dictionary to keep track of all the existing Zone Flyweights.

public class ZoneFactory
{
    private readonly IDictionary<string, Zone> _zones = new Dictionary<string, Zone>();
    private readonly object _lock = new object();

    public Zone GetZone(string zipCode)
    {
        lock (_lock)
        {
            if (_zones.TryGetValue(zipCode, out var zone))
            {
                return zone;
            }

            zone = new Zone(zipCode);
            _zones.Add(zipCode, zone);
            return zone;
        }
    }
}

Finally, the client is free to call the Flyweight Factory and issue Commands on the Flyweight.

public class ZoneClient
{
    static Random rnd = new Random();

    public IEnumerable<ShippingRoute> CreateShippingRoutes(IList<string> usZipCodes)
    {
        var routes = new List<ShippingRoute>();
        var zoneFactory = new ZoneFactory();

        for (var i = 0; i < 2000000; i++)
        {
            var destination = zoneFactory.GetZone(usZipCodes[rnd.Next(usZipCodes.Count)]);

            if(i % 100 == 0) //Issuing a command on the Value Object
                destination = destination.RegisterCourier("Fedex"); 

            routes.Add(new ShippingRoute(destination));
        }

        return routes;
    }
}

UPDATE #1:

It is important to note that Value Objects should not be confused with Value Types (.NET Structs, for example), actually I would prefer implementing Value Objects as immutable Classes rather than Structs, but after all, that's an implementation detail that has nothing to contribute to the conceptual meaning of a Value Object.