Part 2: Object-Oriented World

Most of the examples in the previous part were about a single object that did not have dependencies on other objects (with an exception of some values – strings, integers, enums, etc.). This is not how most OO systems are built. In this part, we are finally going to look at scenarios where multiple objects work together as a system.

This brings about some issues that need to be discussed. One of them is the approach to object-oriented design and how it influences the tools we use to test-drive our code. You probably heard something about a tool called mock objects (at least from one of the introductory chapters of this book) or, in a broader sense, test doubles. If you open your web browser and type “mock objects break encapsulation”, you will find a lot of different opinions – some saying that mocks are great, others blaming them for all the evil in the world, and a lot of opinions that fall in between. The discussions are still heated, even though mocks were introduced more than ten years ago. My goal in this chapter is to outline the context and forces that lead to the adoption of mocks and how to use them for your benefit, not failure.

Steve Freeman, one of the godfathers of using mock objects with TDD, wrote: “mocks arise naturally from doing responsibility-driven OO. All these mock/not-mock arguments are completely missing the point. If you’re not writing that kind of code, people, please don’t give me a hard time”. I am going to introduce mocks in a way that will not give Steve a hard time, I hope.

To do this, I need to cover some topics of object-oriented design. In fact, I decided to dedicate the entire part 2 solely for that purpose. Thus, this chapter will be about object-oriented techniques, practices, and qualities you need to know to use TDD effectively in the object-oriented world. The key quality that we’ll focus on is objects’ composability.

After reading part 2, you will understand an opinionated approach to object-oriented design that is based on the idea of the object-oriented system being a web of nodes (objects) that pass messages to each other. This will give us a good starting point for introducing mock objects and mock-based TDD in part 3.

On Object Composability

In this chapter, I will try to outline briefly why object composability is a goal worth achieving and how it can be achieved. I am going to start with an example of an unmaintainable code and will gradually fix its flaws in the next chapters. For now, we are going to fix just one of the flaws, so the code we will end up will not be perfect by any means, still, it will be better by one quality.

In the coming chapters, we will learn more valuable lessons resulting from changing this little piece of code.

Another task for Johnny and Benjamin

Remember Johnny and Benjamin? Looks like they managed their previous task and are up to something else. Let’s listen to their conversation as they are working on another project…

Benjamin: So, what’s this assignment about?

Johnny: Actually, it’s nothing exciting – we’ll have to add two features to a legacy application that’s not prepared for the changes.

Benjamin: What is the code for?

Johnny: It is a C# class that implements company policies. As the company has just started using this automated system and it was started recently, there is only one policy implemented: yearly incentive plan. Many corporations have what they call incentive plans. These plans are used to promote good behaviors and exceeding expectations by employees of a company.

Benjamin: You mean, the project has just started and is already in a bad shape?

Johnny: Yep. The guys writing it wanted to “keep it simple”, whatever that means, and now it looks pretty bad.

Benjamin: I see…

Johnny: By the way, do you like riddles?

Benjamin: Always!

Johnny: So here’s one: how do you call a development phase when you ensure high code quality?

Benjamin: … … No clue… So what is it called?

Johnny: It’s called “now”.

Benjamin: Oh!

Johnny: Getting back to the topic, here’s the company incentive plan.

Every employee has a pay grade. An employee can be promoted to a higher pay grade, but the mechanics of how that works is something we will not need to deal with.

Normally, every year, everyone gets a raise of 10%. But to encourage behaviors that give an employee a higher pay grade, such an employee cannot get raises indefinitely on a given pay grade. Each grade has its associated maximum pay. If this amount of money is reached, an employee does not get a raise anymore until they reach a higher pay grade.

Additionally, every employee on their 5th anniversary of working for the company gets a special, one-time bonus which is twice their current payment.

Benjamin: Looks like the source code repository just finished synchronizing. Let’s take a bite at the code!

Johnny: Sure, here you go:

 1 public class CompanyPolicies : IDisposable
 2 {
 3   readonly SqlRepository _repository
 4     = new SqlRepository();
 5   
 6   public void ApplyYearlyIncentivePlan()
 7   {
 8     var employees = _repository.CurrentEmployees();
 9 
10     foreach(var employee in employees)
11     {
12       var payGrade = employee.GetPayGrade();
13       //evaluate raise
14       if(employee.GetSalary() < payGrade.Maximum)
15       {
16         var newSalary 
17           = employee.GetSalary() 
18           + employee.GetSalary() 
19           * 0.1;
20         employee.SetSalary(newSalary);
21       }
22   
23       //evaluate one-time bonus
24       if(employee.GetYearsOfService() == 5)
25       {
26         var oneTimeBonus = employee.GetSalary() * 2;
27         employee.SetBonusForYear(2014, oneTimeBonus);
28       }
29   
30       employee.Save();
31     }
32   }
33   
34   public void Dispose()
35   {
36     _repository.Dispose();
37   }
38 }

Benjamin: Wow, there is a lot of literal constants all around and functional decomposition is barely done!

Johnny: Yeah. We won’t be fixing all of that today. Still, we will follow the boy scout rule and “leave the campground cleaner than we found it”.

Benjamin: What’s our assignment?

Johnny: First of all, we need to provide our users with a choice between an SQL database and a NoSQL one. To achieve our goal, we need to be somehow able to make the CompanyPolicies class database type-agnostic. For now, as you can see, the implementation is coupled to the specific SqlRepository, because it creates a specific instance itself:

1 public class CompanyPolicies : IDisposable
2 {
3   readonly SqlRepository _repository
4     = new SqlRepository();

Now, we need to evaluate the options we have to pick the best one. What options do you see, Benjamin?

Benjamin: Well, we could certainly extract an interface from SqlRepository and introduce an if statement to the constructor like this:

 1 public class CompanyPolicies : IDisposable
 2 {
 3   readonly Repository _repository;
 4 
 5   public CompanyPolicies()
 6   {
 7     if(...)
 8     {
 9       _repository = new SqlRepository();
10     }
11     else
12     {
13       _repository = new NoSqlRepository();
14     }
15   }

Johnny: True, but this option has few deficiencies. First of all, remember we’re trying to follow the boy scout rule and by using this option we introduce more complexity to the CommonPolicies class. Also, let’s say tomorrow someone writes another class for, say, reporting and this class will also need to access the repository – they will need to make the same decision on repositories in their code as we do in ours. This effectively means duplicating code. Thus, I’d rather evaluate further options and check if we can come up with something better. What’s our next option?

Benjamin: Another option would be to change the SqlRepository itself to be just a wrapper around the actual database access, like this:

 1 public class SqlRepository : IDisposable
 2 {
 3   readonly Repository _repository;
 4 
 5   public SqlRepository()
 6   {
 7     if(...)
 8     {
 9       _repository = new RealSqlRepository();
10     }
11     else
12     {
13       _repository = new RealNoSqlRepository();
14     }
15   }
16 
17   IList<Employee> CurrentEmployees()
18   {
19     return _repository.CurrentEmployees();
20   }

Johnny: Sure, this is an approach that could work and would be worth considering for very serious legacy code, as it does not force us to change the CompanyPolicies class at all. However, there are some issues with it. First of all, the SqlRepository name would be misleading. Second, look at the CurrentEmployees() method – all it does is delegating a call to the implementation chosen in the constructor. With every new method required of the repository, we’ll need to add new delegating methods. In reality, it isn’t such a big deal, but maybe we can do better than that?

Benjamin: Let me think, let me think… I evaluated the option where CompanyPolicies class chooses between repositories. I also evaluated the option where we hack the SqlRepository to makes this choice. The last option I can think of is leaving this choice to another, “3rd party” code, that would choose the repository to use and pass it to the CompanyPolicies via its constructor, like this:

1 public class CompanyPolicies : IDisposable
2 {
3   private readonly Repository _repository;
4 
5   public CompanyPolicies(Repository repository)
6   {
7     _repository = repository;
8   }

This way, the CompanyPolicies won’t know what exactly is passed to it via its constructor and we can pass whatever we like – either an SQL repository or a NoSQL one!

Johnny: Great! This is the option we’re looking for! For now, just believe me that this approach will lead us to many good things – you’ll see why later.

Benjamin: OK, so let me just pull the SqlRepository instance outside the CompanyPolicies class and make it an implementation of Repository interface, then create a constructor and pass the real instance through it…

Johnny: Sure, I’ll go get some coffee.

… 10 minutes later

Benjamin: Haha! Look at this! I am SUPREME!

 1 public class CompanyPolicies : IDisposable
 2 {
 3   //_repository is now an interface
 4   readonly Repository _repository; 
 5 
 6   // repository is passed from outside.
 7   // We don't know what exact implementation it is.
 8   public CompanyPolicies(Repository repository)
 9   {
10     _repository = repository;
11   }
12   
13   public void ApplyYearlyIncentivePlan()
14   {
15     //... body of the method. Unchanged.
16   }
17   
18   public void Dispose()
19   {
20     _repository.Dispose();
21   }
22 }

Johnny: Hey, hey, hold your horses! There is one thing wrong with this code.

Benjamin: Huh? I thought this is what we were aiming at.

Johnny: Yes, except the Dispose() method. Look closely at the CompanyPolicies class. it is changed so that it is not responsible for creating a repository for itself, but it still disposes of it. This is could cause problems because CompanyPolicies instance does not have any right to assume it is the only object that is using the repository. If so, then it cannot determine the moment when the repository becomes unnecessary and can be safely disposed of.

Benjamin: Ok, I get the theory, but why is this bad in practice? Can you give me an example?

Johnny: Sure, let me sketch a quick example. As soon as you have two instances of CompanyPolicies class, both sharing the same instance of Repository, you’re cooked. This is because one instance of CompanyPolicies may dispose of the repository while the other one may still want to use it.

Benjamin: So who is going to dispose of the repository?

Johnny: The same part of the code that creates it, for example, the Main method. Let me show you an example of how this may look like:

 1 public static void Main(string[] args)
 2 {
 3   using(var repo = new SqlRepository())
 4   {
 5     var policies = new CompanyPolicies(repo);
 6 
 7     //use above created policies 
 8     //for anything you like
 9   }
10 }

This way the repository is created at the start of the program and disposed of at the end. Thanks to this, the CompanyPolicies has no disposable fields and it does not have to be disposable itself – we can just delete the Dispose() method:

 1 //not implementing IDisposable anymore:
 2 public class CompanyPolicies 
 3 {
 4   //_repository is now an interface
 5   readonly Repository _repository; 
 6 
 7   //New constructor
 8   public CompanyPolicies(Repository repository)
 9   {
10     _repository = repository;
11   }
12   
13   public void ApplyYearlyIncentivePlan()
14   {
15     //... body of the method. No changes
16   }
17 
18   //no Dispose() method anymore
19 }

Benjamin: Cool. So, what now? Seems we have the CompanyPolicies class depending on a repository abstraction instead of an actual implementation, like SQL repository. I guess we will be able to make another class implementing the interface for NoSQL data access and just pass it through the constructor instead of the original one.

Johnny: Yes. For example, look at CompanyPolicies component. We can compose it with a repository like this:

1 var policies 
2   = new CompanyPolicies(new SqlRepository());

or like this:

1 var policies 
2   = new CompanyPolicies(new NoSqlRepository());

without changing the code of CompanyPolicies. This means that CompanyPolicies does not need to know what Repository exactly it is composed with, as long as this Repository follows the required interface and meets expectations of CompanyPolicies (e.g. does not throw exceptions when it is not supposed to do so). An implementation of Repository may be itself a very complex and composed of another set of classes, for example, something like this:

1 new SqlRepository(
2   new ConnectionString("..."), 
3   new AccessPrivileges(
4     new Role("Admin"), 
5     new Role("Auditor")
6   ),
7   new InMemoryCache()
8 );

but the CompanyPolicies neither knows or cares about this, as long as it can use our new Repository implementation just like other repositories.

Benjamin: I see… So, getting back to our task, shall we proceed with making a NoSQL implementation of the Repository interface?

Johnny: First, show me the interface that you extracted while I was looking for the coffee.

Benjamin: Here:

1 public interface Repository
2 {
3   IList<Employee> CurrentEmployees();
4 }

Johnny: Ok, so what we need is to create just another implementation and pass it through the constructor depending on what data source is chosen and we’re finished with this part of the task.

Benjamin: You mean there’s more?

Johnny: Yeah, but that’s something for tomorrow. I’m exhausted today.

A Quick Retrospective

In this chapter, Benjamin learned to appreciate composability of an object, i.e. the ability to replace its dependencies, providing different behaviors, without the need to change the code of the object class itself. Thus, an object, given replaced dependencies, starts using the new behaviors without noticing that any change occurred at all.

The code mentioned has some serious flaws. For now, Johnny and Benjamin did not encounter a desperate need to address them.

Also, after we part again with Johnny and Benjamin, we are going to reiterate the ideas they stumble upon in a more disciplined manner.

Telling, not asking

In this chapter, we’ll get back to Johnny and Benjamin as they introduce another change in the code they are working on. In the process, they discover the impact that return values and getters have on the composability of objects.

Contractors

Johnny: G’morning. Ready for another task?

Benjamin: Of course! What’s next?

Johnny: Remember the code we worked on yesterday? It contains a policy for regular employees of the company. But the company wants to start hiring contractors as well and needs to include a policy for them in the application.

Benjamin: So this is what we will be doing today?

Johnny: That’s right. The policy is going to be different for contractors. While, just as regular employees, they will be receiving raises and bonuses, the rules will be different. I made a small table to allow comparing what we have for regular employees and what we want to add for contractors:

So while the workflow is going to be the same for both a regular employee and a contractor:

1. Load from repository
2. Evaluate raise
3. Evaluate bonus
4. Save

the implementation of some of the steps will be different for each type of employee.

Benjamin: Correct me if I am wrong, but these “load” and “save” steps do not look like they belong with the remaining two – they describe something technical, while the other steps describe something strictly related to how the company operates…

Johnny: Good catch, however, this is something we’ll deal with later. Remember the boy scout rule – just don’t make it worse. Still, we’re going to fix some of the design flaws today.

Benjamin: Aww… I’d just fix all of it right away.

Johnny: Ha ha, patience, Luke. For now, let’s look at the code we have now before we plan further steps.

Benjamin: Let me just open my IDE… OK, here it is:

 1 public class CompanyPolicies
 2 {
 3   readonly Repository _repository;
 4 
 5   public CompanyPolicies(Repository repository)
 6   {
 7     _repository = repository;
 8   }
 9   
10   public void ApplyYearlyIncentivePlan()
11   {
12     var employees = _repository.CurrentEmployees();
13 
14     foreach(var employee in employees)
15     {
16       var payGrade = employee.GetPayGrade();
17 
18       //evaluate raise
19       if(employee.GetSalary() < payGrade.Maximum)
20       {
21         var newSalary 
22           = employee.GetSalary() 
23           + employee.GetSalary() 
24           * 0.1;
25         employee.SetSalary(newSalary);
26       }
27   
28       //evaluate one-time bonus
29       if(employee.GetYearsOfService() == 5)
30       {
31         var oneTimeBonus = employee.GetSalary() * 2;
32         employee.SetBonusForYear(2014, oneTimeBonus);
33       }
34   
35       employee.Save();
36     }
37   }
38 }

Benjamin: Look, Johnny, the class, in fact, contains all the four steps you mentioned, but they are not named explicitly – instead, their internal implementation for regular employees is just inserted in here. How are we supposed to add the variation of the employee type?

Johnny: Time to consider our options. We have a few of them. Well?

Benjamin: For now, I can see two. The first one would be to create another class similar to CompanyPolicies, called something like CompanyPoliciesForContractors and implement the new logic there. This would let us leave the original class as is, but we would have to change the places that use CompanyPolicies to use both classes and choose which one to use somehow. Also, we would have to add a separate method to the repository for retrieving the contractors.

Johnny: Also, we would miss our chance to communicate through the code that the sequence of steps is intentionally similar in both cases. Others who read this code in the future will see that the implementation for regular employees follows the steps: load, evaluate raise, evaluate bonus, save. When they look at the implementation for contractors, they will see the same order of steps, but they will be unable to tell whether the similarity is intentional, or a pure accident.

Benjamin: So our second option is to put an if statement into the differing steps inside the CompanyPolicies class, to distinguish between regular employees and contractors. The Employee class would have an isContractor() method and depending on what it would return, we would either execute the logic for regular employees or contractors. Assuming that the current structure of the code looks like this:

 1 foreach(var employee in employees)
 2 {
 3   //evaluate raise
 4   ...
 5   
 6   //evaluate one-time bonus
 7   ...
 8   
 9   //save employee
10 }

the new structure would look like this:

 1 foreach(var employee in employees)
 2 {
 3   if(employee.IsContractor())
 4   {
 5     //evaluate raise for contractor
 6     ...
 7   }
 8   else
 9   {
10     //evaluate raise for regular
11     ...
12   }
13 
14   if(employee.IsContractor())
15   {
16     //evaluate one-time bonus for contractor
17     ...
18   }
19   else
20   {
21     //evaluate one-time bonus for regular
22     ...
23   }
24   
25   //save employee
26   ...
27 }

this way we would show that the steps are the same, but the implementation is different. Also, this would mostly require us to add code and not move the existing code around.

Johnny: The downside is that we would make the class even uglier than it was when we started. So despite initial easiness, we’ll be doing a huge disservice to future maintainers. We have at least one another option. What would that be?

Benjamin: Let’s see… we could move all the details concerning the implementation of the steps from CompanyPolicies class into the Employee class itself, leaving only the names and the order of steps in CompanyPolicies:

1 foreach(var employee in employees)
2 {
3   employee.EvaluateRaise();
4   employee.EvaluateOneTimeBonus();
5   employee.Save();
6 }

Then, we could change the Employee into an interface, so that it could be either a RegularEmployee or ContractorEmployee – both classes would have different implementations of the steps, but the CompanyPolicies would not notice, since it would not be coupled to the implementation of the steps anymore – just the names and the order.

Johnny: This solution would have one downside – we would need to significantly change the current code, but you know what? I’m willing to do it, especially that I was told today that the logic is covered by some tests which we can run to see if a regression was introduced.

Benjamin: Cool, what do we start with?

Johnny: The first thing that is between us and our goal are these getters on the Employee class:

1 GetSalary();
2 GetGrade();
3 GetYearsOfService();

They just expose too much information specific to the regular employees. It would be impossible to use different implementations when these are around. These setters don’t help much:

1 SetSalary(newSalary);
2 SetBonusForYear(year, amount);

While these are not as bad, we’d better give ourselves more flexibility. Thus, let’s hide all of it behind more abstract methods that only reveal our intention.

First, take a look at this code:

1 //evaluate raise
2 if(employee.GetSalary() < payGrade.Maximum)
3 {
4   var newSalary
5     = employee.GetSalary()
6     + employee.GetSalary()
7     * 0.1;
8   employee.SetSalary(newSalary);
9 }

Each time you see a block of code separated from the rest with blank lines and starting with a comment, you see something screaming “I want to be a separate method that contains this code and has a name after the comment!”. Let’s grant this wish and make it a separate method on the Employee class.

Benjamin: Ok, wait a minute… here:

1 employee.EvaluateRaise();

Johnny: Great! Now, we’ve got another example of this species here:

1 //evaluate one-time bonus
2 if(employee.GetYearsOfService() == 5)
3 {
4   var oneTimeBonus = employee.GetSalary() * 2;
5   employee.SetBonusForYear(2014, oneTimeBonus);
6 }

Benjamin: This one should be even easier… Ok, take a look:

1 employee.EvaluateOneTimeBonus();

Johnny: Almost good. I’d only leave out the information that the bonus is one-time from the name.

Benjamin: Why? Don’t we want to include what happens in the method name?

Johnny: Actually, no. What we want to include is our intention. The bonus being one-time is something specific to the regular employees and we want to abstract away the details about this or that kind of employee, so that we can plug in different implementations without making the method name lie. The names should reflect that we want to evaluate a bonus, whatever that means for a particular type of employee. Thus, let’s make it:

1 employee.EvaluateBonus();

Benjamin: Ok, I get it. No problem.

Johnny: Now let’s take a look at the full code of the EvaluateIncentivePlan method to see whether it is still coupled to details specific to regular employees. Here’s the code:

 1 public void ApplyYearlyIncentivePlan()
 2 {
 3   var employees = _repository.CurrentEmployees();
 4 
 5   foreach(var employee in employees)
 6   {
 7     employee.EvaluateRaise();
 8     employee.EvaluateBonus();
 9     employee.Save();
10   }
11 }

Benjamin: It seems that there is no coupling to the details about regular employees anymore. Thus, we can safely make the repository return a combination of regulars and contractors without this code noticing anything. Now I think I understand what you were trying to achieve. If we make interactions between objects happen on a more abstract level, then we can put in different implementations with less effort.

Johnny: True. Can you see another thing related to the lack of return values on all of the Employee’s methods in the current implementation?

Benjamin: Not really. Does it matter?

Johnny: Well, if Employee methods had return values and this code depended on them, all subclasses of Employee would be forced to supply return values as well and these return values would need to match the expectations of the code that calls these methods, whatever these expectations were. This would make introducing other kinds of employees harder. But now that there are no return values, we can, for example:

• introduce a TemporaryEmployee that has no raises, by leaving its EvaluateRaise() method empty, and the code that uses employees will not notice.
• introduce a ProbationEmployee that has no bonus policy, by leaving its EvaluateBonus() method empty, and the code that uses employees will not notice.
• introduce an InMemoryEmployee that has an empty Save() method, and the code that uses employees will not notice.

As you see, by asking the objects less, and telling it more, we get greater flexibility to create alternative implementations and the composability, which we talked about yesterday, increases!

Benjamin: I see… So telling objects what to do instead of asking them for their data makes the interactions between objects more abstract, and so, more stable, increasing composability of interacting objects. This is a valuable lesson – it is the first time I hear this and it seems a pretty powerful concept.

A Quick Retrospective

In this chapter, Benjamin learned that the composability of an object (not to mention clarity) is reinforced when interactions between it and its peers are: abstract, logical and stable. Also, he discovered, with Johnny’s help, that it is further strengthened by following a design style where objects are told what to do instead of asked to give away information to somebody who then decides on their behalf. This is because if an API of an abstraction is built around answering specific questions, the clients of the abstraction tend to ask it a lot of questions and are coupled to both those questions and some aspects of the answers (i.e. what is in the return values). This makes creating another implementation of abstraction harder, because each new implementation of the abstraction needs to not only provide answers to all those questions, but the answers are constrained to what the client expects. When abstraction is merely told what its client wants it to achieve, the clients are decoupled from most of the details of how this happens. This makes introducing new implementations of abstraction easier – it often even lets us define implementations with all methods empty without the client noticing at all.

These are all important conclusions that will lead us towards TDD with mock objects.

Time to leave Johnny and Benjamin for now. In the next chapter, I’m going to reiterate their discoveries and put them in a broader context.

The need for mock objects

We already experienced mock objects in the chapter about tools, although at that point, I gave you an oversimplified and deceiving explanation of what a mock object is, promising that I will make up for it later. Now is the time.

Mock objects were made with a specific goal in mind. I hope that when you understand the real goal, you will probably understand the means to the goal far better.

In this chapter, we will explore the qualities of object-oriented design which make mock objects a viable tool.

Composability… again!

In the two previous chapters, we followed Johnny and Benjamin in discovering the benefits of and prerequisites for composability of objects. Composability is the number one quality of the design we’re after. After reading Johhny and Benjamin’s story, you might have some questions regarding composability. Hopefully, they are among the ones answered in the next few chapters. Ready?

Why do we need composability?

It might seem stupid to ask this question here – if you have managed to stay with me this long, then you’re probably motivated enough not to need a justification? Well, anyway, it’s still worth discussing it a little. Hopefully, you’ll learn as much reading this back-to-basics chapter as I did writing it.

Pre-object-oriented approaches

Back in the days of procedural programming¹, when we wanted to execute different code based on some factor, it was usually achieved using an ‘if’ statement. For example, if our application was in need to be able to use different kinds of alarms, like a loud alarm (that plays a loud sound) and a silent alarm (that does not play any sound, but instead silently contacts the police) interchangeably, then usually, we could achieve this using a conditional like in the following function:

 1 void triggerAlarm(Alarm* alarm)
 2 {
 3   if(alarm->kind == LOUD_ALARM)
 4   {
 5     playLoudSound(alarm);
 6   }
 7   else if(alarm->kind == SILENT_ALARM)
 8   {
 9     notifyPolice(alarm);
10   }
11 }

The code above makes a decision based on the alarm kind which is embedded in the alarm structure:

1 struct Alarm
2 {
3   int kind;
4   //other data
5 };

If the alarm kind is the loud one, it executes behavior associated with a loud alarm. If this is a silent alarm, the behavior for silent alarms is executed. This seems to work. Unfortunately, if we wanted to make a second decision based on the alarm kind (e.g. we needed to disable the alarm), we would need to query the alarm kind again. This would mean duplicating the conditional code, just with a different set of actions to perform, depending on what kind of alarm we were dealing with:

 1 void disableAlarm(Alarm* alarm)
 2 {
 3   if(alarm->kind == LOUD_ALARM)
 4   {
 5     stopLoudSound(alarm);
 6   }
 7   else if(alarm->kind == SILENT_ALARM)
 8   {
 9     stopNotifyingPolice(alarm);
10   }
11 }

Do I have to say why this duplication is bad? Do I hear a “no”? My apologies then, but I’ll tell you anyway. The duplication means that every time a new kind of alarm is introduced, a developer has to remember to update both places that contain ‘if-else’ – the compiler will not force this. As you are probably aware, in the context of teams, where one developer picks up work that another left and where, from time to time, people leave to find another job, expecting someone to “remember” to update all the places where the logic is duplicated is asking for trouble.

So, we see that the duplication is bad, but can we do something about it? To answer this question, let’s take a look at the reason the duplication was introduced. And the reason is: We have two things we want to be able to do with our alarms: triggering and disabling. In other words, we have a set of questions we want to be able to ask an alarm. Each kind of alarm has a different way of answering these questions – resulting in having a set of “answers” specific to each alarm kind:

So, at least conceptually, as soon as we know the alarm kind, we already know which set of behaviors (represented as a row in the above table) it needs. We could just decide the alarm kind once and associate the right set of behaviors with the data structure. Then, we would not have to query the alarm kind in several places as we did, but instead, we could say: “execute triggering behavior from the set of behaviors associated with this alarm, whatever it is”.

Unfortunately, procedural programming does not allow binding behavior with data easily. The whole paradigm of procedural programming is about separating behavior and data! Well, honestly, they had some answers to those concerns, but these answers were mostly awkward (for those of you that still remember C language: I’m talking about macros and function pointers). So, as data and behavior are separated, we need to query the data each time we want to pick a behavior based on it. That’s why we have duplication.

Object-oriented programming to the rescue!

On the other hand, object-oriented programming has for a long time made available two mechanisms that enable what we didn’t have in procedural languages:

1. Classes – that allow binding behavior together with data.
2. Polymorphism – allows executing behavior without knowing the exact class that holds them, but knowing only a set of behaviors that it supports. This knowledge is obtained by having an abstract type (interface or an abstract class) define this set of behaviors, with no real implementation. Then we can make other classes that provide their own implementation of the behaviors that are declared to be supported by the abstract type. Finally, we can use the instances of those classes where an instance of the abstract type is expected. In the case of statically-typed languages, this requires implementing an interface or inheriting from an abstract class.

So, in case of our alarms, we could make an interface with the following signature:

1 public interface Alarm
2 {
3   void Trigger();
4   void Disable();
5 }

and then make two classes: LoudAlarm and SilentAlarm, both implementing the Alarm interface. Example for LoudAlarm:

 1 public class LoudAlarm : Alarm
 2 {
 3   public void Trigger()
 4   {
 5     //play very loud sound
 6   }
 7 
 8   public void Disable()
 9   {
10     //stop playing the sound
11   }
12 }

Now, we can make parts of code use the alarm, but by knowing the interface only instead of the concrete classes. This makes the parts of the code that use alarm this way not having to check which alarm they are dealing with. Thus, what previously looked like this:

1 if(alarm->kind == LOUD_ALARM)
2 {
3   playLoudSound(alarm);
4 }
5 else if(alarm->kind == SILENT_ALARM)
6 {
7   notifyPolice(alarm);
8 }

becomes just:

1 alarm.Trigger();

where alarm is either LoudAlarm or SilentAlarm but seen polymorphically as Alarm, so there’s no need for ‘if-else’ anymore.

But hey, isn’t this cheating? Even provided I can execute the trigger behavior on an alarm without knowing the actual class of the alarm, I still have to decide which class it is in the place where I create the actual instance:

1 // we must know the exact type here:
2 alarm = new LoudAlarm(); 

so it looks like I am not eliminating the ‘else-if’ after all, just moving it somewhere else! This may be true (we will talk more about it in future chapters), but the good news is that I eliminated at least the duplication by making our dream of “picking the right set of behaviors to use with certain data once” come true.

Thanks to this, I create the alarm once, and then I can take it and pass it to ten, a hundred or a thousand different places where I will not have to determine the alarm kind anymore to use it correctly.

This allows writing a lot of classes that do not know about the real class of the alarm they are dealing with, yet they can use the alarm just fine only by knowing a common abstract type – Alarm. If we can do that, we arrive at a situation where we can add more alarms implementing Alarm and watch existing objects that are already using Alarm work with these new alarms without any change in their source code! There is one condition, however – the creation of the alarm instances must be moved out of the classes that use them. That’s because, as we already observed, to create an alarm using a new operator, we have to know the exact type of the alarm we are creating. So whoever creates an instance of LoudAlarm or SilentAlarm, loses its uniformity, since it is not able to depend solely on the Alarm interface.

The power of composition

Moving creation of alarm instances away from the classes that use those alarms brings up an interesting problem – if an object does not create the objects it uses, then who does it? A solution is to make some special places in the code that are only responsible for composing a system from context-independent objects². We saw this already as Johnny was explaining composability to Benjamin. He used the following example:

1 new SqlRepository(
2   new ConnectionString("..."),
3   new AccessPrivileges(
4     new Role("Admin"),
5     new Role("Auditor")
6   ),
7   new InMemoryCache()
8 );

We can do the same with our alarms. Let’s say that we have a secure area that has three buildings with different alarm policies:

• Office building – the alarm should silently notify guards during the day (to keep office staff from panicking) and loud during the night, when guards are on patrol.
• Storage building – as it is quite far and the workers are few, we want to trigger loud and silent alarms at the same time.
• Guards building – as the guards are there, no need to notify them. However, a silent alarm should call the police for help instead, and a loud alarm is desired as well.

Note that besides just triggering a loud or silent alarm, we are required to support a combination (“loud and silent alarms at the same time”) and a conditional (“silent during the day and loud during the night”). we could just hardcode some fors and if-elses in our code, but instead, let’s factor out these two operations (combination and choice) into separate classes implementing the alarm interface.

Let’s call the class implementing the choice between two alarms DayNightSwitchedAlarm. Here is the source code:

 1 public class DayNightSwitchedAlarm : Alarm
 2 {
 3   private readonly Alarm _dayAlarm;
 4   private readonly Alarm _nightAlarm;
 5 
 6   public DayNightSwitchedAlarm(
 7     Alarm dayAlarm,
 8     Alarm nightAlarm)
 9   {
10     _dayAlarm = dayAlarm;
11     _nightAlarm = nightAlarm;
12   }
13 
14   public void Trigger()
15   {
16     if(/* is day */)
17     {
18       _dayAlarm.Trigger();
19     }
20     else
21     {
22       _nightAlarm.Trigger();
23     }
24   }
25 
26   public void Disable()
27   {
28     _dayAlarm.Disable();
29     _nightAlarm.Disable();
30   }
31 }

Studying the above code, it is apparent that this is not an alarm per se, e.g. it does not raise any sound or notification, but rather, it contains some rules on how to use other alarms. This is the same concept as power splitters in real life, which act as electric devices but do not do anything other than redirecting the electricity to other devices.

Next, let’s use the same approach and model the combination of two alarms as a class called HybridAlarm. Here is the source code:

 1 public class HybridAlarm : Alarm
 2 {
 3   private readonly Alarm _alarm1;
 4   private readonly Alarm _alarm2;
 5 
 6   public HybridAlarm(
 7     Alarm alarm1,
 8     Alarm alarm2)
 9   {
10     _alarm1 = alarm1;
11     _alarm2 = alarm2;
12   }
13 
14   public void Trigger()
15   {
16     _alarm1.Trigger();
17     _alarm2.Trigger();
18   }
19 
20   public void Disable()
21   {
22     _alarm1.Disable();
23     _alarm2.Disable();
24   }
25 }

Using these two classes along with already existing alarms, we can implement the requirements by composing instances of those classes like this:

 1 new SecureArea(
 2   new OfficeBuilding(
 3     new DayNightSwitchedAlarm(
 4       new SilentAlarm("222-333-444"),
 5       new LoudAlarm()
 6     )
 7   ),
 8   new StorageBuilding(
 9     new HybridAlarm(
10       new SilentAlarm("222-333-444"),
11       new LoudAlarm()
12     )
13   ),
14   new GuardsBuilding(
15     new HybridAlarm(
16       new SilentAlarm("919"), //call police
17       new LoudAlarm()
18     )
19   )
20 );

Note that the fact that we implemented combination and choice of alarms as separate objects implementing the Alarm interface allows us to define new, interesting alarm behaviors using the parts we already have, but composing them together differently. For example, we might have, as in the above example:

1 new DayNightSwitchAlarm(
2   new SilentAlarm("222-333-444"),
3   new LoudAlarm());

which would mean triggering silent alarm during a day and loud one during the night. However, instead of this combination, we might use:

1 new DayNightSwitchAlarm(
2   new SilentAlarm("222-333-444"),
3   new HybridAlarm(
4     new SilentAlarm("919"),
5     new LoudAlarm()
6   )
7 )

Which would mean that we use a silent alarm to notify the guards during the day, but a combination of silent (notifying police) and loud during the night. Of course, we are not limited to combining a silent alarm with a loud one only. We can as well combine two silent ones:

1 new HybridAlarm(
2   new SilentAlarm("919"),
3   new SilentAlarm("222-333-444")
4 )

Additionally, if we suddenly decided that we do not want alarm at all during the day, we could use a special class called NoAlarm that would implement Alarm interface, but have both Trigger and Disable methods do nothing. The composition code would look like this:

1 new DayNightSwitchAlarm(
2   new NoAlarm(), // no alarm during the day
3   new HybridAlarm(
4     new SilentAlarm("919"),
5     new LoudAlarm()
6   )
7 )

And, last but not least, we could completely remove all alarms from the guards building using the following NoAlarm class (which is also an Alarm):

 1 public class NoAlarm : Alarm
 2 {
 3   public void Trigger()
 4   {
 5   }
 6 
 7   public void Disable()
 8   {
 9   }
10 }

and passing it as the alarm to guards building:

1 new GuardsBuilding(
2   new NoAlarm()
3 )

Noticed something funny about the last few examples? If not, here goes an explanation: in the last few examples, we have twisted the behaviors of our application in wacky ways, but all of this took place in the composition code! We did not have to modify any other existing classes! True, we had to write a new class called NoAlarm, but did not need to modify any code except the composition code to make objects of this new class work with objects of existing classes!

This ability to change the behavior of our application just by changing the way objects are composed together is extremely powerful (although you will always be able to achieve it only to certain extent), especially in evolutionary, incremental design, where we want to evolve some pieces of code with as little as possible other pieces of code having to realize that the evolution takes place. This ability can be achieved only if our system consists of composable objects, thus the need for composability – an answer to a question raised at the beginning of this chapter.

Summary – are you still with me?

We started with what seemed to be a repetition from a basic object-oriented programming course, using a basic example. It was necessary though to make a fluent transition to the benefits of composability we eventually introduced at the end. I hope you did not get overwhelmed and can understand now why I am putting so much stress on composability.

In the next chapter, we will take a closer look at composing objects itself.

Web, messages and protocols

In the previous chapter, we talked a little bit about why composability is valuable, now let’s flesh out a little bit of terminology to get more precise understanding.

So, again, what does it mean to compose objects?

Roughly, it means that an object has obtained a reference to another object and can invoke methods on it. By being composed together, two objects form a small system that can be expanded with more objects as needed. Thus, a bigger object-oriented system forms something similar to a web:

If we take the web metaphor a little bit further, we can note some similarities to e.g. a TCP/IP network:

1. An object can send messages to other objects (i.e. call methods on them – arrows on the above diagram) via interfaces. Each message has a sender and at least one recipient.
2. To send a message to a recipient, a sender has to acquire an address of the recipient, which, in the object-oriented world, we call a reference (and in languages such as C++, references are just that – addresses in memory).
3. Communication between the sender and recipients has to follow a certain protocol. For example, the sender usually cannot invoke a method passing nulls as all arguments, or should expect an exception if it does so. Don’t worry if you don’t see the analogy now – I’ll follow up with more explanation of this topic later).

Alarms, again!

Let’s try to apply this terminology to an example. Imagine that we have an anti-fire alarm system in an office. When triggered, this alarm system makes all lifts go to the bottom floor, opens them and then disables each of them. Among others, the office contains automatic lifts, that contain their own remote control systems and mechanical lifts, that are controlled from the outside by a special custom-made mechanism.

Let’s try to model this behavior in code. As you might have guessed, we will have some objects like alarm, automatic lift, and mechanical lift. The alarm will control the lifts when triggered.

Firstly, we don’t want the alarm to have to distinguish between an automatic and a mechanical lift – this would only add complexity to the alarm system, especially that there are plans to add a third kind of lift – a more modern one – in the future. So, if we made the alarm aware of the different kinds of lifts, we would have to modify it each time a new kind of lift is introduced. Thus, we need a special interface (let’s call it Lift) to communicate with both AutoLift and MechanicalLift (and ModernLift in the future). Through this interface, an alarm will be able to send messages to both types of lifts without having to know the difference between them.

 1 public interface Lift
 2 {
 3   ...
 4 }
 5 
 6 public class AutoLift : Lift
 7 {
 8   ...
 9 }
10 
11 public class MechanicalLift : Lift
12 {
13   ...
14 }

Next, to be able to communicate with specific lifts through the Lift interface, an alarm object has to acquire “addresses” of the lift objects (i.e. references to them). We can pass these references e.g. through a constructor:

 1 public class Alarm
 2 {
 3   private readonly IEnumerable<Lift> _lifts;
 4 
 5   //obtain "addresses" here
 6   public Alarm(IEnumerable<Lift> lifts)
 7   {
 8     //store the "addresses" for later use
 9     _lifts = lifts;
10   }
11 }

Then, the alarm can send three kinds of messages: GoToBottomFloor(), OpenDoor(), and DisablePower() to any of the lifts through the Lift interface:

1 public interface Lift
2 {
3   void GoToBottomFloor();
4   void OpenDoor();
5   void DisablePower();
6 }

and, as a matter of fact, it sends all these messages when triggered. The Trigger() method on the alarm looks like this:

1 public void Trigger()
2 {
3   foreach(var lift in _lifts)
4   {
5     lift.GoToBottomFloor();
6     lift.OpenDoor();
7     lift.DisablePower();
8   }
9 }

By the way, note that the order in which the messages are sent does matter. For example, if we disabled the power first, asking the powerless lift to go anywhere would be impossible. This is a first sign of a protocol existing between the Alarm and a Lift.

In this communication, Alarm is a sender – it knows what it sends (messages that control lifts), it knows why (because the alarm is triggered), but does not know what exactly are the recipients going to do when they receive the message – it only knows what it wants them to do, but does not know how they are going to achieve it. The rest is left to objects that implement Lift (namely, AutoLift and MechanicalLift). They are the recipients – they don’t know who they received the message from (unless they are told in the content of the message somehow – but even then they can be cheated), but they know how to react, based on who they are (AutoLift has its specific way of reacting and MechanicalLift has its own as well). They also know what kind of message they received (a lift does a different thing when asked to go to the bottom floor than when it is asked to open its door) and what’s the message content (i.e. method arguments – in this simplistic example there are none).

To illustrate that this separation between a sender and a recipient exists, I’ll say that we could even write an implementation of a Lift interface that would just ignore the messages it got from the Alarm (or fake that it did what it was asked for) and the Alarm will not even notice. We sometimes say that this is because deciding on a specific reaction is not the Alarm’s responsibility.

New requirements

It was decided that whenever any malfunction happens in the lift when it is executing the alarm emergency procedure, the lift object should report this by throwing an exception called LiftUnoperationalException. This affects both Alarm and implementations of the Lift interface:

1. The Lift implementations need to know that when a malfunction happens, they should report it by throwing the exception.
2. The Alarm must be ready to handle the exception thrown from lifts and act accordingly (e.g. still try to secure other lifts).

This is another example of a protocol existing between Alarm and Lift that must be adhered to by both sides. Here is an exemplary code of Alarm keeping to its part of the protocol, i.e. handling the malfunction reports in its Trigger() method:

 1 public void Trigger()
 2 {
 3   foreach(var lift in _lifts)
 4   {
 5     try
 6     {
 7       lift.GoToBottomFloor();
 8       lift.OpenDoor();
 9       lift.DisablePower();
10     }
11     catch(LiftUnoperationalException e)
12     {
13       report.ThatCannotSecure(lift);
14     }
15   }
16 }

Summary

Each of the objects in the web can receive messages and most of them send messages to other objects. Throughout the next chapters, I will refer to an object sending a message as sender and an object receiving a message as recipient.

For now, it may look unjustified to introduce this metaphor of webs, protocols, interfaces, etc. Still, I have two reasons for doing so:

• This is the way I interpret Alan Kay’s mental model of what object-oriented programming is about.
• I find it useful for some things want to explain in the next chapters: how to make connections between objects, how to design an object boundary and how to achieve strong composability.

By the way, the example from this chapter is a bit naive. For one, in real production code, the lifts would have to be notified in parallel, not sequentially. Also, I would probably use some kind of observer pattern to separate the instructions give to each lift from raising an event (I will demonstrate an example of using observers in this fashion in the next chapter). These two choices, in turn, would probably make me rethink error handling - there is a chance I wouldn’t be able to get away with just catching exceptions. Anyway, I hope the naive form helped explain the idea of protocols and messages without raising the bar in other topics.

Composing a web of objects

Three important questions

Now that we know that such thing as a web of objects exists, that there are connections, protocols and such, time to mention the one thing I left out: how does a web of objects come into existence?

This is, of course, a fundamental question, because if we are unable to build a web, we don’t have a web. Also, this is a question that is a little more tricky than it looks like at first glance. To answer it, we have to find the answer to three other questions:

1. When are objects composed (i.e. when are the connections made)?
2. How does an object obtain a reference to another one on the web (i.e. how are the connections made)?
3. Where are objects composed (i.e. where are connections made)?

At first sight, finding the difference between these questions may be tedious, but the good news is that they are the topic of this chapter, so I hope we’ll have that cleared shortly.

A preview of all three answers

Before we take a deep dive, let’s try to answer these three questions for a naive example code of a console application:

1 public static void Main(string[] args)
2 {
3   var sender = new Sender(new Recipient());
4 
5   sender.Work();
6 }

This is a piece of code that creates two objects and connects them, then it tells the sender object to work on something. For this code, the answers to the three questions I raised are:

1. When are objects composed? Answer: during application startup (because Main() method is called at console application startup).
2. How does an object (Sender) obtain a reference to another one (Recipient)? Answer: the reference is obtained by receiving a Recipient as a constructor parameter.
3. Where are objects composed? Answer: at the application entry point (Main() method)

Depending on circumstances, we may have different sets of answers. Also, to avoid rethinking this topic each time we create an application, I like to have a set of default answers to these questions. I’d like to demonstrate these answers by tackling each of the three questions in-depth, one by one, in the coming chapters.

When are objects composed?

The quick answer to this question is: as early as possible. Now, that wasn’t too helpful, was it? So here goes a clarification.

Many of the objects we use in our applications can be created and connected up-front when the application starts and can stay alive until the application finishes executing. Let’s call this part the static part of the web.

Apart from that, there’s something I’ll call dynamic part – the objects that are created, connected and destroyed many times during the application lifecycle. There are at least two reasons this dynamic part exists:

1. Some objects represent requests or user actions that arrive during the application runtime, are processed and then discarded. These objects cannot be created up-front, but only as early as the events they represent occur. Also, these objects do not live until the application is terminated but are discarded as soon as the processing of a request is finished. Other objects represent e.g. items in cache that live for some time and then expire, so, again, we don’t have enough information to compose these objects up-front and they often don’t live as long as the application itself. Such objects come and go, making temporary connections.
2. There are objects that have life spans as long as the application has, but the nature of their connections are temporary. Consider an example where we want to encrypt our data storage for export, but depending on circumstances, we sometimes want to export it using one algorithm and sometimes using another. If so, we may sometimes invoke the encryption method like this:

1   database.encryptUsing(encryption1);

and sometimes like this:

1   database.encryptUsing(encryption2);

In the first case, database and encryption1 are only connected temporarily, for the time it takes to perform the encryption. Still, nothing prevents these objects from being created during the application startup. The same applies to the connection of database and encryption2 - this connection is temporary as well.

Given these definitions, it is perfectly possible for an object to be part of both static and dynamic part – some of its connections may be made up-front, while others may be created later, e.g. when its reference is passed inside a message sent to another object (i.e. when it is passed as method parameter).

How does a sender obtain a reference to a recipient (i.e. how connections are made)?

There are several ways a sender can obtain a reference to a recipient, each of them being useful in certain circumstances. These ways are:

1. Receive as a constructor parameter
2. Receive inside a message (i.e. as a method parameter)
3. Receive in response to a message (i.e. as a method return value)
4. Receive as a registered observer

Let’s take a closer look at what each of them is about and which one to choose in what circumstances.

Receive as a constructor parameter

Two objects can be composed by passing one into a constructor of another:

1 sender = new Sender(recipient);

A sender that receives the recipient then saves a reference to it in a private field for later, like this:

1 private Recipient _recipient;
2 
3 public Sender(Recipient recipient)
4 {
5   _recipient = recipient;
6 }

Starting from this point, the Sender may send messages to Recipient at will:

1 public void DoSomething()
2 {
3   //... other code
4 
5   _recipient.DoSomethingElse();
6 
7   //... other code
8 }

Advantage: “what you hide, you can change”

Composing using constructors has one significant advantage. Let’s look again at how Sender is created:

1 sender = new Sender(recipient);

and at how it’s used:

1 sender.DoSomething();

Note that only the code that creates a Sender needs to be aware of it having access to a Recipient. When it comes to invoking a method, this private reference is invisible from outside. Now, remember when I described the principle of separating object use from its construction? If we follow this principle here, we end up with the code that creates a Sender being in a totally different place than the code that uses it. Thus, every code that uses a Sender will not be aware of it sending messages to a Recipient at all. There is a maxim that says: “what you hide, you can change”³ – in this particular case, if we decide that the Sender does not need a Recipient to do its job, all we have to change is the composition code to remove the Recipient:

1 //no need to pass a reference to Recipient anymore
2 new Sender();

and the code that uses Sender doesn’t need to change at all – it still looks the same as before, since it never knew Recipient:

1 sender.DoSomething();

Communication of intent: required recipient

Another advantage of the constructor approach is that it allows stating explicitly what the required recipients are for a particular sender. For example, a Sender accepts a Recipient in its constructor:

1 public Sender(Recipient recipient)
2 {
3  //...
4 }

The signature of the constructor makes it explicit that a reference to Recipient is required for a Sender to work correctly – the compiler will not allow creating a Sender without passing something as a Recipient⁴.

Where to apply

Passing into a constructor is a great solution in cases we want to compose a sender with a recipient permanently (i.e. for the lifetime of a Sender). To be able to do this, a Recipient must, of course, exist before a Sender does. Another less obvious requirement for this composition is that a Recipient must be usable at least as long as a Sender is usable. A simple example of violating this requirement is this code:

1 sender = new Sender(recipient);
2 
3 recipient.Dispose(); //but sender is unaware of it
4                      //and may still use recipient later:
5 sender.DoSomething();

In this case, when we tell sender to DoSomething(), it uses a recipient that is already disposed of, which may lead to some nasty bugs.

Receive inside a message (i.e. as a method parameter)

Another common way of composing objects together is passing one object as a parameter of another object’s method call:

1 sender.DoSomethingWithHelpOf(recipient);

In such a case, the objects are most often composed temporarily, just for the time of execution of this single method:

1 public void DoSomethingWithHelpOf(Recipient recipient)
2 {
3   //... perform some logic
4 
5   recipient.HelpMe();
6 
7   //... perform some logic
8 }

Where to apply

Contrary to the constructor approach, where a Sender could hide from its user the fact that it needs a Recipient, in this case, the user of Sender is explicitly responsible for supplying a Recipient. In other words, there needs to be some kind of coupling between the code using Sender and a Recipient. It may look like this coupling is a disadvantage, but I know of some scenarios where it’s required for code using Sender to be able to provide its own Recipient – it allows us to use the same sender with different recipients at different times (most often from different parts of the code):

1 //in one place
2 sender.DoSomethingWithHelpOf(recipient);
3 
4 //in another place:
5 sender.DoSomethingWithHelpOf(anotherRecipient);
6 
7 //in yet another place:
8 sender.DoSomethingWithHelpOf(yetAnotherRecipient);

If this ability is not required, I strongly prefer the constructor approach as it removes the (then) unnecessary coupling between code using Sender and a Recipient, giving me more flexibility.

Receive in response to a message (i.e. as a method return value)

This method of composing objects relies on an intermediary object – often an implementation of a factory pattern – to supply recipients on request. To simplify things, I will use factories in examples presented in this section, although what I tell you is true for some other creational patterns as well (also, later in this chapter, I’ll cover some aspects of the factory pattern in depth).

To be able to ask a factory for recipients, the sender needs to obtain a reference to it first. Typically, a factory is composed with a sender through its constructor (an approach I already described). For example:

1 var sender = new Sender(recipientFactory);

The factory can then be used by the Sender at will to get a hold of new recipients:

 1 public class Sender
 2 {
 3   //...
 4 
 5   public void DoSomething()
 6   {
 7     //ask the factory for a recipient:
 8     var recipient = _recipientFactory.CreateRecipient();
 9 
10     //use the recipient:
11     recipient.DoSomethingElse();
12   }
13 }

Where to apply

I find this kind of composition useful when a new recipient is needed each time DoSomething() is called. In this sense, it may look much like in case of the previously discussed approach of receiving a recipient inside a message. There is one difference, however. Contrary to passing a recipient inside a message, where the code using the Sender passed a Recipient “from outside” of the Sender, in this approach, we rely on a separate object that is used by a Sender “from the inside”.

To be more clear, let’s compare the two approaches. Passing recipient inside a message looks like this:

1 //Sender gets a Recipient from the "outside":
2 public void DoSomething(Recipient recipient)
3 {
4   recipient.DoSomethingElse();
5 }

and obtaining it from a factory:

1 //a factory is used "inside" Sender
2 //to obtain a recipient
3 public void DoSomething()
4 {
5   var recipient = _factory.CreateRecipient();
6   recipient.DoSomethingElse();
7 }

So in the first example, the decision on which Recipient is used is made by whoever calls DoSomething(). In the factory example, whoever calls DoSomething() does not know at all about the Recipient and cannot directly influence which Recipient is used. The factory makes this decision.

Factories with parameters

So far, all of the factories we considered had creation methods with empty parameter lists, but this is not a requirement of any sort - I just wanted to make the examples simple, so I left out everything that didn’t help make my point. As the factory remains the decision-maker on which Recipient is used, it can rely on some external parameters passed to the creation method to help it make the decision.

Not only factories

Throughout this section, we have used a factory as our role model, but the approach of obtaining a recipient in response to a message is wider than that. Other types of objects that fall into this category include, among others: repositories, caches, builders, collections⁵. While they are all important concepts (which you can look up on the web if you like), they are not required to progress through this chapter so I won’t go through them now.

Receive as a registered observer

This means passing a recipient to an already created sender (contrary to passing as constructor parameter where the recipient was passed during creation) as a parameter of a method that stores the reference for later use. Usually, I meet two kinds of registrations:

1. a “setter” method, where someone registers an observer by calling something like sender.SetRecipient(recipient)method. Honestly, even though it’s a setter, I don’t like naming it according to the convention “setWhatever()” – after Kent Beck⁶ I find this convention too much implementation-focused instead of purpose-focused. Thus, I pick different names based on what domain concept is modeled by the registration method or what is its purpose. Anyway, this approach allows only one observer and setting another overwrites the previous one.
2. an “addition” method - where someone registers an observer by calling something like sender.addRecipient(recipient) - in this approach, a collection of observers needs to be maintained somewhere and the recipient registered as an observer is merely added to the collection.

Note that there is one similarity to the “passing inside a message” approach – in both, a recipient is passed inside a message. The difference is that this time, contrary to “pass inside a message” approach, the passed recipient is not used immediately (and then forgotten), but rather it’s remembered (registered) for later use.

I hope I can clear up the confusion with a quick example.

Example

Suppose we have a temperature sensor that can report its current and historically mean value to whoever subscribes to it. If no one subscribes, the sensor still does its job, because it still has to collect the data for calculating a history-based mean value in case anyone subscribes later.

We may model this behavior by using an observer pattern and allow observers to register in the sensor implementation. If no observer is registered, the values are not reported (in other words, a registered observer is not required for the object to function, but if there is one, it can take advantage of the reports). For this purpose, let’s make our sensor depend on an interface called TemperatureObserver that could be implemented by various concrete observer classes. The interface declaration looks like this:

1 public interface TemperatureObserver
2 {
3   void NotifyOn(
4     Temperature currentValue,
5     Temperature meanValue);
6 }

Now we’re ready to look at the implementation of the temperature sensor itself and how it uses this TemperatureObserver interface. Let’s say that the class representing the sensor is called TemperatureSensor. Part of its definition could look like this:

 1 public class TemperatureSensor
 2 {
 3   private TemperatureObserver _observer
 4     = new NullObserver(); //ignores reported values
 5 
 6   private Temperature _meanValue
 7     = Temperature.Celsius(0);
 8 
 9   // + maybe more fields related to storing historical data
10 
11   public void Run()
12   {
13     while(/* needs to run */)
14     {
15       var currentValue = /* get current value somehow */;
16       _meanValue = /* update mean value somehow */;
17 
18       _observer.NotifyOn(currentValue, _meanValue);
19 
20       WaitUntilTheNextMeasurementTime();
21     }
22   }
23 }

As you can see, by default, the sensor reports its values to nowhere (NullObserver), which is a safe default value (using a null for a default value instead would cause exceptions or force us to put a null check inside the Run() method). We have already seen such “null objects”⁷ a few times before (e.g. in the previous chapter, when we introduced the NoAlarm class) – NullObserver is just another incarnation of this pattern.

Registering observers

Still, we want to be able to supply our own observer one day, when we start caring about the measured and calculated values (the fact that we “started caring” may be indicated to our application e.g. by a network packet or an event from the user interface). This means we need to have a method inside the TemperatureSensor class to overwrite this default “do-nothing” observer with a custom one after the TemperatureSensor instance is created. As I said, I don’t like the “SetXYZ()” convention, so I will name the registration method FromNowOnReportTo() and make the observer an argument. Here are the relevant parts of the TemperatureSensor class:

 1 public class TemperatureSensor
 2 {
 3   private TemperatureObserver _observer
 4     = new NullObserver(); //ignores reported values
 5 
 6   //... ... ...
 7 
 8   public void FromNowOnReportTo(TemperatureObserver observer)
 9   {
10     _observer = observer;
11   }
12 
13   //... ... ...
14 }

This allows us to overwrite the current observer with a new one should we ever need to do it. Note that, as I mentioned, this is the place where the registration approach differs from the “pass inside a message” approach, where we also received a recipient in a message, but for immediate use. Here, we don’t use the recipient (i.e. the observer) when we get it, but instead, we save it for later use.

Communication of intent: optional dependency

Allowing registering recipients after a sender is created is a way of saying: “the recipient is optional – if you provide one, fine, if not, I will do my work without it”. Please, don’t use this kind of mechanism for required recipients – these should all be passed through a constructor, making it harder to create invalid objects that are only partially ready to work.

Let’s examine an example of a class that:

• accepts a recipient in its constructor,
• allows registering a recipient as an observer,
• accepts a recipient for a single method invocation

This example is annotated with comments that sum up what these three approaches say:

 1 public class Sender
 2 {
 3   //"I will not work without a Recipient1"
 4   public Sender(Recipient1 recipient1) {...}
 5 
 6   //"I will do fine without Recipient2 but you
 7   //can overwrite the default here if you are
 8   //interested in being notified about something
 9   //or want to customize my default behavior"
10   public void Register(Recipient2 recipient2) {...}
11 
12   //"I need a recipient3 only here and you get to choose
13   //what object to give me each time you invoke 
14   //this method on me"
15   public void DoSomethingWith(Recipient3 recipient3) {...}
16 }

More than one observer

Now, the observer API we just skimmed over gives us the possibility to have a single observer at any given time. When we register a new observer, the reference to the old one is overwritten. This is not really useful in our context, is it? With real sensors, we often want them to report their measurements to multiple places (e.g. we want the measurements printed on the screen, saved to a database, and used as part of more complex calculations). This can be achieved in two ways.

The first way would be to just hold a collection of observers in our sensor, and add to this collection whenever a new observer is registered:

1 private IList<TemperatureObserver> _observers
2   = new List<TemperatureObserver>();
3 
4 public void FromNowOnReportTo(TemperatureObserver observer)
5 {
6   _observers.Add(observer);
7 }

In such case, reporting would mean iterating over the list of observers:

1 ...
2 foreach(var observer in _observers)
3 {
4   observer.NotifyOn(currentValue, meanValue);
5 }
6 ...

The approach shown above places the policy for notifying observers inside the sensor. Many times this could be sufficient. Still, the sensor is coupled to the answers to at least the following questions:

• In what order do we notify the observers? In the example above, we notify them in order of registration.
• How do we handle errors (e.g. one of the observers throws an exception) - do we stop notifying further observers, or log an error and continue, or maybe do something else? In the example above, we stop on the first observer that throws an exception and rethrow the exception. Maybe it’s not the best approach for our case?
• Is our notification model synchronous or asynchronous? In the example above, we are using a synchronous for loop.

We can gain a bit more flexibility by extracting the notification logic into a separate observer that would receive a notification and pass it to other observers. We can call it “a broadcasting observer”. The implementation of such an observer could look like this:

 1 public class BroadcastingObserver
 2   : TemperatureObserver,
 3     TemperatureObservable //I'll explain it in a second
 4 {
 5   private IList<TemperatureObserver> _observers
 6     = new List<TemperatureObserver>();
 7 
 8   public void FromNowOnReportTo(TemperatureObserver observer)
 9   {
10     _observers.Add(observer);
11   }
12 
13   public void NotifyOn(
14     Temperature currentValue,
15     Temperature meanValue)
16   {
17     foreach(var observer in _observers)
18     {
19       observer.NotifyOn(currentValue, meanValue);
20     }
21   }
22 }

This BroadcastingObserver could be instantiated and registered like this:

 1 //instantiation:
 2 var broadcastingObserver
 3   = new BroadcastingObserver();
 4 
 5 ...
 6 //somewhere else in the code...:
 7 sensor.FromNowOnReportTo(broadcastingObserver);
 8 
 9 ...
10 //somewhere else in the code...:
11 broadcastingObserver.FromNowOnReportTo(
12       new DisplayingObserver())
13 ...
14 //somewhere else in the code...:
15 broadcastingObserver.FromNowOnReportTo(
16       new StoringObserver());
17 ...
18 //somewhere else in the code...:
19 broadcastingObserver.FromNowOnReportTo(
20       new CalculatingObserver());

With this design, the other observers register with the broadcasting observer. However, they don’t really need to know who they are registering with - to hide it, I introduced a special interface called TemperatureObservable, which has the FromNowOnReportTo() method:

1 public interface TemperatureObservable
2 {
3   public void FromNowOnReportTo(TemperatureObserver observer);
4 }

This way, the code that registers an observer does not need to know what the concrete observable object is.

The additional benefit of modeling broadcasting as an observer is that it would allow us to change the broadcasting policy without touching either the sensor code or the other observers. For example, we might replace our for loop-based observer with something like ParallelBroadcastingObserver that would notify each of its observers asynchronously instead of sequentially. The only thing we would need to change is the observer object that’s registered with a sensor. So instead of:

1 //instantiation:
2 var broadcastingObserver
3   = new BroadcastingObserver();
4 
5 ...
6 //somewhere else in the code...:
7 sensor.FromNowOnReportTo(broadcastingObserver);

We would have

1 //instantiation:
2 var broadcastingObserver
3   = new ParallelBroadcastingObserver();
4 
5 ...
6 //somewhere else in the code...:
7 sensor.FromNowOnReportTo(broadcastingObserver);

and the rest of the code would remain unchanged. This is because the sensor implements:

• TemperatureObserver interface, which the sensor depends on,
• TemperatureObservable interface which the code that registers the observers depends on.

Anyway, as I said, use registering instances very wisely and only if you specifically need it. Also, if you do use it, evaluate how allowing changing observers at runtime is affecting your multithreading scenarios. This is because a collection of observers might potentially be modified by two threads at the same time.

Where are objects composed?

Ok, we went through some ways of passing a recipient to a sender. We did it from the “internal” perspective of a sender that is given a recipient. What we left out, for the most part, is the “external” perspective, i.e. who should pass the recipient into the sender?

For almost all of the approaches described in the previous chapter, there is no limitation – you pass the recipient from where you need to pass it.

There is one approach, however, that is more limited, and this approach is passing as a constructor parameter.

Why is that? Because, we are trying to be true to the principle of “separating objects creation from use” and this, in turn, is a result of us striving for composability.

Anyway, if an object cannot both use and create another object, we have to make special objects just for creating other objects (there are some design patterns for how to design such objects, but the most popular and useful is a factory) or defer the creation up to the application entry point (there is also a pattern for this, called composition root).

So, we have two cases to consider. I’ll start with the second one – composition root.

Composition Root

let’s assume, just for fun, that we are creating a mobile game where a player has to defend a castle. This game has two levels. Each level has a castle to defend. When we manage to defend the castle long enough, the level is considered completed and we move to the next one. So, we can break down the domain logic into three classes: a Game that has two Levels and each of them that contains a Castle. Let’s also assume that the first two classes violate the principle of separating use from construction, i.e. that a Game creates its own levels and each Level creates its own castle.

A Game class is created in the Main() method of the application:

1 public static void Main(string[] args)
2 {
3   var game = new Game();
4 
5   game.Play();
6 }

The Game creates its own Level objects of specific classes implementing the Level interface and stores them in an array:

1 public class Game
2 {
3   private Level[] _levels = new[] {
4     new Level1(), new Level2()
5   };
6 
7   //some methods here that use the levels
8 }

And the Level implementations create their own castles and assign them to fields of interface type Castle:

 1 public class Level1
 2 {
 3   private Castle _castle = new SmallCastle();
 4 
 5   //some methods here that use the castle
 6 }
 7 
 8 public class Level2
 9 {
10   private Castle _castle = new BigCastle();
11 
12   //some methods here that use the castle
13 }

Now, I said (and I hope you see it in the code above) that the Game, Level1 and Level2 classes violate the principle of separating use from construction. We don’t like this, do we? Let’s try to make them more compliant with the principle.

Achieving separation of use from construction

First, let’s refactor the Level1 and Level2 according to the principle by moving the instantiation of their castles outside. As the existence of a castle is required for a level to make sense at all – we will say this in code by using the approach of passing a castle through a Level’s constructor:

 1 public class Level1
 2 {
 3   private Castle _castle;
 4 
 5   //now castle is received as
 6   //constructor parameter
 7   public Level1(Castle castle)
 8   {
 9     _castle = castle;
10   }
11 
12   //some methods here that use the castle
13 }
14 
15 public class Level2
16 {
17   private Castle _castle;
18 
19   //now castle is received as
20   //constructor parameter
21   public Level2(Castle castle)
22   {
23     _castle = castle;
24   }
25 
26   //some methods here that use the castle
27 }

This was easy, wasn’t it? However, it leaves us with an issue to resolve: if the instantiations of castles are not in Level1 and Level2 anymore, then they have to be passed by whoever creates the levels. In our case, this falls on the shoulders of Game class:

 1 public class Game
 2 {
 3   private Level[] _levels = new[] {
 4     //now castles are created here as well:
 5     new Level1(new SmallCastle()),
 6     new Level2(new BigCastle())
 7   };
 8 
 9   //some methods here that use the levels
10 }

But remember – this class suffers from the same violation of not separating objects use from construction as the levels did. Thus, to make this class compliant to the principle as well, we have to treat it the same as we did the level classes – move the creation of levels outside:

 1 public class Game
 2 {
 3   private Level[] _levels;
 4 
 5   //now levels are received as 
 6   //constructor parameter
 7   public Game(Level[] levels)
 8   {
 9     _levels = levels;
10   }
11 
12   //some methods here that use the levels
13 }

There, we did it, but again, the levels now must be supplied by whoever creates the Game. Where do we put them? In our case, the only choice left is the Main() method of our application, so this is exactly where we are going to create all the objects that we pass to a Game:

 1 public static void Main(string[] args)
 2 {
 3   var game =
 4     new Game(
 5       new Level[] { 
 6         new Level1(new SmallCastle()),
 7         new Level2(new BigCastle())
 8   });
 9 
10   game.Play();
11 }

By the way, the Level1 and Level2 are differed only by the castle types and this difference is no more as we refactored it out, so we can make them a single class and call it e.g. TimeSurvivalLevel (because such level is considered completed when we manage to defend our castle for a specific period). After this move, now we have:

 1 public static void Main(string[] args)
 2 {
 3   var game =
 4     new Game(
 5       new Level[] {
 6         new TimeSurvivalLevel(new SmallCastle()),
 7         new TimeSurvivalLevel(new BigCastle())
 8   });
 9 
10   game.Play();
11 }

Looking at the code above, we might come to another funny conclusion – this violates the principle of separating use from construction as well! First, we create and connect the web of objects and then send the Play() message to the game object. Can we fix this as well?

I would say “no”, for two reasons:

1. There is no further place we can defer the creation. Sure, we could move the creation of the Game object and its dependencies into a separate object responsible only for the creation (e.g. a factory), but it would still leave us with the question: where do we create the factory? Of course, we could use a static method to call it in our Main() like this: var app = ApplicationRoot.Create(), but that would be delegating the composition, not pulling it up.
2. The whole point of the principle we are trying to apply is decoupling, i.e. giving ourselves the ability to change one thing without having to change another. When we think of it, there is no point of decoupling the entry point of the application from the application itself, since this is the most application-specific and non-reusable part of the application we can imagine.

What I consider important is that we reached a place where the web of objects is created using the constructor approach and we have no place left to defer the creation of the web (in other words, it is as close as possible to application entry point). Such a place is called a composition root.

We say that composition root is “as close as possible” to the application entry point because there may be different frameworks in control of your application and you will not always have the Main() method at your service⁸.

Apart from the constructor invocations, the composition root may also contain, e.g., registrations of observers (see registration approach to passing recipients) if such observers are already known at this point. It is also responsible for disposing of all objects it created that require explicit disposal after the application finishes running. This is because it creates them and thus it is the only place in the code that can safely determine when they are not needed.

The composition root above looks quite small, but you can imagine it growing a lot in bigger applications. There are techniques of refactoring the composition root to make it more readable and cleaner – we will explore such techniques in a dedicated chapter.

Factories

Earlier, I described how it isn’t always possible to pass everything through the constructor. One of the approaches we discussed that we can use in such cases is a factory.

When we previously talked about factories, we focused on it being just a source of objects. This time we will have a much closer look at what factories are and what are their benefits.

But first, let’s look at an example of a factory emerging in code that was not using it, as a mere consequence of trying to follow the principle of separating objects use from construction.

Emerging factory – example

Consider the following code that receives a frame that came from the network (as raw data), then packs it into an object, validates and applies to the system:

 1 public class MessageInbound
 2 {
 3   //...initialization code here...
 4 
 5   public void Handle(Frame frame)
 6   {
 7     // determine the type of message
 8     // and wrap it with an object
 9     ChangeMessage change = null;
10     if(frame.Type == FrameTypes.Update)
11     {
12       change = new UpdateRequest(frame);
13     }
14     else if(frame.Type == FrameTypes.Insert)
15     {
16       change = new InsertRequest(frame);
17     }
18     else
19     {
20       throw
21         new InvalidRequestException(frame.Type);
22     }
23 
24     change.ValidateUsing(_validationRules);
25     _system.Apply(change);
26   }
27 }

Note that this code violates the principle of separating use from construction. The change is first created, depending on the frame type, and then used (validated and applied) in the same method. On the other hand, if we wanted to separate the construction of change from its use, we have to note that it is impossible to pass an instance of the ChangeMessage through the MessageInbound constructor, because this would require us to create the ChangeMessage before we create the MessageInbound. Achieving this is impossible because we can create messages only as soon as we know the frame data which the MessageInbound receives.

Thus, our choice is to make a special object that we would move the creation of new messages into. It would produce new instances when requested, hence the name factory. The factory itself can be passed through a constructor since it does not require a frame to exist – it only needs one when it is asked to create a message.

Knowing this, we can refactor the above code to the following:

 1 public class MessageInbound
 2 {
 3   private readonly
 4     MessageFactory _messageFactory;
 5   private readonly
 6     ValidationRules _validationRules;
 7   private readonly
 8     ProcessingSystem _system;
 9 
10   public MessageInbound(
11     //this is the factory:
12     MessageFactory messageFactory,
13     ValidationRules validationRules,
14     ProcessingSystem system)
15   {
16     _messageFactory = messageFactory;
17     _validationRules = validationRules;
18     _system = system;
19   }
20 
21   public void Handle(Frame frame)
22   {
23     var change = _messageFactory.CreateFrom(frame);
24     change.ValidateUsing(_validationRules);
25     _system.Apply(change);
26   }
27 }

This way we have separated message construction from its use.

By the way, note that we extracted not only a single constructor, but the whole object creation logic. It’s in the factory now:

 1 public class InboundMessageFactory
 2  : MessageFactory
 3 {
 4   ChangeMessage CreateFrom(Frame frame)
 5   {
 6     if(frame.Type == FrameTypes.Update)
 7     {
 8       return new UpdateRequest(frame);
 9     }
10     else if(frame.Type == FrameTypes.Insert)
11     {
12       return new InsertRequest(frame);
13     }
14     else
15     {
16       throw
17         new InvalidRequestException(frame.Type);
18     }
19   }
20 }

And that’s it. We have a factory now and the way we got to this point was by trying to adhere to the principle of separating use from construction.

Now that we are through with the example, we’re ready for some more general explanation on factories.

Reasons to use factories

As demonstrated in the example, factories are objects responsible for creating other objects. They are used to achieve the separation of objects construction from their use. They are useful for creating objects that live shorter than the objects that use them. Such a shorter lifespan results from not all of the context necessary to create an object being known up-front (i.e. until a user enters credentials, we would not be able to create an object representing their account). We pass the part of the context we know up-front (a so-called global context) in the factory via its constructor and supply the rest that becomes available later (the so-called local context) in a form of factory method parameters when it becomes available:

1 var factory = new Factory(globalContextKnownUpFront);
2 
3 //... some time later:
4 factory.CreateInstance(localContext);

Another case for using a factory is when we need to create a new object each time some kind of request is made (a message is received from the network or someone clicks a button):

 1 var factory = new Factory(globalContext);
 2 
 3 //...
 4 
 5 //we need a fresh instance
 6 factory.CreateInstance();
 7 
 8 //...
 9 
10 //we need another fresh instance
11 factory.CreateInstance();

In the above example, two independent instances are created, even though both are created identically (there is no local context that would differentiate them).

Both these reasons were present in our example from the last chapter:

1. We were unable to create a ChangeMessage before knowing the actual Frame.
2. For each Frame received, we needed to create a new ChangeMessage instance.

Simplest factory

The simplest possible example of a factory object is something along the following lines:

1 public class MyMessageFactory
2 {
3   public MyMessage CreateMyMessage()
4   {
5     return new MyMessage();
6   }
7 }

Even in this primitive shape the factory already has some value (e.g. we can make MyMessage an abstract type and return instances of its subclasses from the factory, and the only place impacted by the change is the factory itself⁹). More often, however, when talking about simple factories, I think about something like this:

1 //Let's assume MessageFactory
2 //and Message are interfaces
3 public class XmlMessageFactory : MessageFactory
4 {
5   public Message CreateSessionInitialization()
6   {
7     return new XmlSessionInitialization();
8   }
9 }

Note the two things that the factory in the second example has that the one in the first example did not:

• it implements an interface (a level of indirection is introduced)
• its CreateSessionInitialization() method declares a return type to be an interface (another level of indirection is introduced)

Thus, we introduced two additional levels of indirection. For you to be able to use factories effectively, I need you to understand why and how these levels of indirection are useful, especially when I talk with people, they often do not understand the benefits of using factories, “because we already have the new operator to create objects”. The point is, by hiding (encapsulating) certain information, we achieve more flexibility:

Factories allow creating objects polymorphically (encapsulation of type)

Each time we invoke a new operator, we have to put the name of a concrete type next to it:

1 new List<int>(); //OK!
2 new IList<int>(); //won't compile...

This means that whenever we change our mind and instead of using List<int>() we want to use an object of another class (e.g. SortedList<int>()), we have to either change the code to delete the old type name and put new type name or provide some kind of conditional (if-else). Both options have drawbacks:

• changing the name of the type requires a code change in the class that calls the constructor each time we change our mind, effectively tying us to a single implementation,
• conditionals require us to know all the possible subclasses up-front and our class lacks extensibility that we often require.

Factories allow dealing with these deficiencies. Because we get objects from a factory by invoking a method, not by saying explicitly which class we want to get instantiated, we can take advantage of polymorphism, i.e. our factory may have a method like this:

1 IList<int> CreateContainerForData() {...}

which returns any instance of a real class that implements IList<int> (say, List<int>):

1 public IList<int> /* return type is interface */ 
2 CreateContainerForData()
3 {
4   return new List<int>(); /* instance of concrete class */
5 }

Of course, it makes little sense for the return type of the factory to be a library class or interface like in the above example (rather, we use factories to create instances of our own classes), but you get the idea, right?

Anyway, it’s typical for a declared return type of a factory to be an interface or, at worst, an abstract class. This means that whoever uses the factory, it knows only that it receives an object of a class that is implementing an interface or is derived from an abstract class. But it doesn’t know exactly what concrete type it is. Thus, a factory may return objects of different types at different times, depending on some rules only it knows.

Time to look at a more realistic example of how to apply this. Let’s say we have a factory of messages like this:

 1 public class Version1ProtocolMessageFactory
 2   : MessageFactory
 3 {
 4   public Message NewInstanceFrom(MessageData rawData)
 5   {
 6     if(rawData.IsSessionInit())
 7     {
 8       return new SessionInit(rawData);
 9     }
10     else if(rawData.IsSessionEnd())
11     {
12       return new SessionEnd(rawData);
13     }
14     else if(rawData.IsSessionPayload())
15     {
16       return new SessionPayload(rawData);
17     }
18     else
19     {
20       throw new UnknownMessageException(rawData);
21     }
22   }
23 }

The factory can create many different types of messages depending on what is inside the raw data, but from the perspective of the user of the factory, this is irrelevant. All that it knows is that it gets a Message, thus, it (and the rest of the code operating on messages in the whole application for that matter) can be written as general-purpose logic, containing no “special cases” dependent on the type of message:

1 var message = _messageFactory.NewInstanceFrom(rawData);
2 message.ValidateUsing(_primitiveValidations);
3 message.ApplyTo(_sessions);

Note that this code doesn’t need to change in case we want to add a new type of message that’s compatible with the existing flow of processing messages¹⁰. The only place we need to modify in such a case is the factory. For example, imagine we decided to add a session refresh message. The modified factory would look like this:

 1 public class Version1ProtocolMessageFactory
 2   : MessageFactory
 3 {
 4   public Message NewInstanceFrom(MessageData rawData)
 5   {
 6     if(rawData.IsSessionInit())
 7     {
 8       return new SessionInit(rawData);
 9     }
10     else if(rawData.IsSessionEnd())
11     {
12       return new SessionEnd(rawData);
13     }
14     else if(rawData.IsSessionPayload())
15     {
16       return new SessionPayload(rawData);
17     }
18     else if(rawData.IsSessionRefresh())
19     {
20       //new message type!
21       return new SessionRefresh(rawData);
22     }
23     else
24     {
25       throw new UnknownMessageException(rawData);
26     }
27   }
28 }

and the rest of the code could remain untouched.

Using the factory to hide the real type of message returned makes maintaining the code easier, because there are fewer places in the code impacted by adding new types of messages to the system or removing existing ones (in our example – in case when we do not need to initiate a session anymore) ¹¹ – the factory hides that and the rest of the application is coded against the general scenario.

The above example demonstrated how a factory can hide that many classes can play the same role (i.e. different messages could play the role of a Message), but we can as well use factories to hide that the same class plays many roles. An object of the same class can be returned from different factory method, each time as a different interface and clients cannot access the methods it implements from other interfaces.

Factories are themselves polymorphic (encapsulation of rule)

Another benefit of factories over inline constructor calls is that if a factory is received an object that can be passed as an interface, which allows us to use another factory that implements the same interface in its place via polymorphism. This allows replacing the rule used to create objects with another one, by replacing one factory implementation with another.

Let’s get back to the example from the previous section, where we had a Version1ProtocolMessageFactory that could create different kinds of messages based on some flags being set on raw data (e.g. IsSessionInit(), IsSessionEnd() etc.). Imagine we decided we don’t like this version anymore. The reason is that having so many separate boolean flags is too cumbersome, as with such a design, we risk receiving a message where two or more flags are set to true (e.g. someone might send a message that indicates that it’s both a session initialization and a session end). Supporting such cases (e.g. by validating and rejecting such messages) requires additional effort in the code. We want to make it better before more customers start using the protocol. Thus, a new version of the protocol is conceived – a version 2. This version, instead of using several flags, uses an enum (called MessageTypes) to specify the message type:

1 public enum MessageTypes
2 {
3   SessionInit,
4   SessionEnd,
5   SessionPayload,
6   SessionRefresh
7 }

thus, instead of querying different flags, version 2 allows querying a single value that defines the message type.

Unfortunately, to sustain backward compatibility with some clients, both versions of the protocol need to be supported, each version hosted on a separate endpoint. The idea is that when all clients migrate to the new version, the old one will be retired.

Before introducing version 2, the composition root had code that looked like this:

1 var controller = new MessagingApi(new Version1ProtocolMessageFactory());
2 //...
3 controller.HostApi(); //start listening to messages

where MessagingApi has a constructor accepting the MessageFactory interface:

1 public MessagingApi(MessageFactory messageFactory)
2 {
3   _messageFactory = messageFactory;
4 }

and some general message handling code:

1 var message = _messageFactory.NewInstanceFrom(rawData);
2 message.ValidateUsing(_primitiveValidations);
3 message.ApplyTo(_sessions);

This logic needs to remain the same in both versions of the protocol. How do we achieve this without duplicating this code for each version?

The solution is to create another message factory, i.e. another class implementing the MessageFactory interface. Let’s call it Version2ProtocolMessageFactory and implement it like this:

 1 //note that now it is a version 2 protocol factory
 2 public class Version2ProtocolMessageFactory
 3   : MessageFactory
 4 {
 5   public Message NewInstanceFrom(MessageData rawData)
 6   {
 7     switch(rawData.GetMessageType())
 8     {
 9       case MessageTypes.SessionInit:
10         return new SessionInit(rawData);
11       case MessageTypes.SessionEnd:
12         return new SessionEnd(rawData);
13       case MessageTypes.SessionPayload:
14         return new SessionPayload(rawData);
15       case MessageTypes.SessionRefresh:
16         return new SessionRefresh(rawData);
17       default:
18         throw new UnknownMessageException(rawData);
19     }
20   }
21 }

Note that this factory can return objects of the same classes as version 1 factory, but it makes the decision using the value obtained from GetMessageType() method instead of relying on the flags.

Having this factory enables us to create a MessagingApi instance working with either the version 1 protocol:

1 new MessagingApi(new Version1ProtocolMessageFactory());

or the version 2 protocol:

1 new MessagingApi(new Version2ProtocolMessageFactory());

and, since for the time being we need to support both versions, our composition root will have this code somewhere¹²:

1 var v1Controller = new MessagingApi(new Version1ProtocolMessageFactory());
2 var v2Controller = new MessagingApi(new Version2ProtocolMessageFactory());
3 //...
4 v1Controller.HostApi(); //start listening to messages
5 v2Controller.HostApi(); //start listening to messages

Note that the MessagingApi class itself did not need to change. As it depends on the MessageFactory interface, all we had to do was supplying a different factory object that made its decision differently.

This example shows something I like calling “encapsulation of rule”. The logic inside the factory is a rule on how, when and which objects to create. Thus, if we make our factory implement an interface and have other objects depend on this interface only, we will be able to switch the rules of object creation by providing another factory without having to modify these objects (as in our case where we did not need to modify the MessagingApi class).

Factories can hide some of the created object dependencies (encapsulation of global context)

Let’s consider another toy example. We have an application that, again, can process messages. One of the things that are done with those messages is saving them in a database and another is validation. The processing of the message is, like in previous examples, handled by a MessageProcessing class, which, this time, does not use any factory, but creates the messages based on the frame data itself. Let’s look at this class:

 1 public class MessageProcessing
 2 {
 3   private DataDestination _database;
 4   private ValidationRules _validation;
 5 
 6   public MessageProcessing(
 7     DataDestination database,
 8     ValidationRules validation)
 9   {
10     _database = database;
11     _validation = validation;
12   }
13 
14   public void ApplyTo(MessageData data)
15   {
16     //note this creation:
17     var message =
18       new Message(data, _database, _validation);
19 
20     message.Validate();
21     message.Persist();
22 
23     //... other actions
24   }
25 }

There is one noticeable thing about the MessageProcessing class. It depends on both DataDestination and ValidationRules interfaces but does not use them. The only thing it needs those interfaces for is to supply them as parameters to the constructor of a Message. As the number of Message constructor parameters grows, the MessageProcessing will have to change to take more parameters as well. Thus, the MessageProcessing class gets polluted by something that it does not directly need.

We can remove these dependencies from MessageProcessing by introducing a factory that would take care of creating the messages in its stead. This way, we only need to pass DataDestination and ValidationRules to the factory, because MessageProcessing never needed them for any reason other than creating messages. This factory may look like this:

 1 public class MessageFactory
 2 {
 3   private DataDestination _database;
 4   private ValidationRules _validation;
 5 
 6   public MessageFactory(
 7     DataDestination database,
 8     ValidationRules validation)
 9   {
10     _database = database;
11     _validation = validation;
12   }
13 
14   //clients only need to pass data here:
15   public Message CreateFrom(MessageData data)
16   {
17     return
18       new Message(data, _database, _validation);
19   }
20 }

Now, note that the creation of messages was moved to the factory, along with the dependencies needed for this. The MessageProcessing does not need to take these dependencies anymore, and can stay more true to its real purpose:

 1 public class MessageProcessing
 2 {
 3   private MessageFactory _factory;
 4 
 5   //now we depend on the factory only:
 6   public MessageProcessing(
 7     MessageFactory factory)
 8   {
 9     _factory = factory;
10   }
11 
12   public void ApplyTo(MessageData data)
13   {
14     //no need to pass database and validation
15     //since they already are inside the factory:
16     var message = _factory.CreateFrom(data);
17 
18     message.Validate();
19     message.Persist();
20 
21     //... other actions
22   }
23 }

So, instead of DataDestination and ValidationRules interfaces, the MessageProcessing depends only on the factory. This may not sound like a very attractive tradeoff (taking away two dependencies and introducing one), but note that whenever the MessageFactory needs another dependency that is like the existing two, the factory is all that will need to change. The MessageProcessing will remain untouched and still coupled only to the factory.

The last thing that I want to mention is that not all dependencies can be hidden inside a factory. Note that the factory still needs to receive the MessageData from whoever is asking for a Message, because the MessageData is not available when the factory is created. You may remember that I call such dependencies a local context (because it is specific to a single use of a factory and passed from where the factory creation method is called). On the other hand, what a factory accepts through its constructor can be called a global context (because it is the same throughout the factory lifetime). Using this terminology, the local context cannot be hidden from users of the factory, but the global context can. Thanks to this, the classes using the factory do not need to know about the global context and can stay cleaner, coupled to less things and more focused.

Factories can help increase readability and reveal intention (encapsulation of terminology)

Let’s assume we are writing an action-RPG game that consists of many game levels (not to be mistaken with experience levels). Players can start a new game or continue a saved game. When they choose to start a new game, they are immediately taken to the first level with an empty inventory and no skills. Otherwise, when they choose to continue an old game, they have to select a file with a saved state (then the game level, skills, and inventory are loaded from the file). Thus, we have two separate workflows in our game that end up with two different methods being invoked: OnNewGame() for a new game mode and OnContinue() for resuming a saved game:

1 public void OnNewGame()
2 {
3   //...
4 }
5 
6 public void OnContinue(PathToFile savedGameFilePath)
7 {
8   //...
9 }

In each of these methods, we have to somehow assemble a Game class instance. The constructor of Game allows composing it with a starting level, character’s inventory and a set of skills the character can use:

1 public class FantasyGame : Game
2 {
3   public FantasyGame(
4       Level startingLevel,
5       Inventory inventory,
6       Skills skills)
7   {
8   }
9 }

There is no special class for “new game” or for “resumed game” in our code. A new game is just a game starting from the first level with an empty inventory and no skills:

1 var newGame = new FantasyGame(
2   new FirstLevel(),
3   new BackpackInventory(),
4   new KnightSkills());

In other words, the “new game” concept is expressed by a composition of objects rather than by a single class, called e.g. NewGame.

Likewise, when we want to create a game object representing a resumed game, we do it like this:

 1 try
 2 {
 3   saveFile.Open();
 4 
 5   var loadedGame = new FantasyGame(
 6     saveFile.LoadLevel(),
 7     saveFile.LoadInventory(),
 8     saveFile.LoadSkills());
 9 }
10 finally
11 {
12   saveFile.Close();
13 }

Again, the concept of “resumed game” is represented by a composition rather than a single class, just like in the case of “new game”. On the other hand, the concepts of “new game” and “resumed game” are part of the domain, so we must make them explicit somehow or we lose readability.

One of the ways to do this is to use a factory¹³. We can create such a factory and put inside two methods: one for creating a new game, another for creating a resumed game. The code of the factory could look like this:

 1 public class FantasyGameFactory : GameFactory
 2 {
 3   public Game NewGame()
 4   {
 5     return new FantasyGame(
 6       new FirstLevel(),
 7       new BackpackInventory(),
 8       new KnightSkills());
 9   }
10 
11   public Game GameSavedIn(PathToFile savedGameFilePath)
12   {
13     var saveFile = new SaveFile(savedGameFilePath);
14     try
15     {
16       saveFile.Open();
17 
18       var loadedGame = new FantasyGame(
19         saveFile.LoadLevel(),
20         saveFile.LoadInventory(),
21         saveFile.LoadSkills());
22 
23       return loadedGame;
24     }
25     finally
26     {
27       saveFile.Close();
28     }
29   }
30 }

Now we can use the factory in the place where we are notified of the user choice. Remember? This was the place:

1 public void OnNewGame()
2 {
3   //...
4 }
5 
6 public void OnContinue(PathToFile savedGameFilePath)
7 {
8   //...
9 }

When we fill the method bodies with the factory usage, the code ends up like this:

 1 public void OnNewGame()
 2 {
 3   var game = _gameFactory.NewGame();
 4   game.Start();
 5 }
 6 
 7 public void OnContinue(PathToFile savedGameFilePath)
 8 {
 9   var game = _gameFactory.GameSavedIn(savedGameFilePath);
10   game.Start();
11 }

Note that using a factory helps in making the code more readable and intention-revealing. Instead of using a nameless set of connected objects, the two methods shown above ask using terminology from the domain (explicitly requesting either NewGame() or GameSavedIn(path)). Thus, the domain concepts of “new game” and “resumed game” become explicit. This justifies the first part of the name I gave this section (i.e. “Factories can help increase readability and reveal intention”).

There is, however, the second part of the section name: “encapsulating terminology” which I need to explain. Here’s an explanation: note that the factory is responsible for knowing what exactly the terms “new game” and “resumed game” mean. As the meaning of the terms is encapsulated in the factory, we can change this meaning throughout the application merely by changing the code inside the factory. For example, we can say that new game starts with inventory that is not empty, but contains a basic sword and a shield, by changing the NewGame() method of the factory to this:

1   public Game NewGame()
2   {
3     return new FantasyGame(
4       new FirstLevel(),
5       new BackpackInventory(
6         new BasicSword(),
7         new BasicShield()),
8       new KnightSkills());
9   }

Putting it all together, factories allow giving names to some specific object compositions to increase readability and they allow hiding the meaning of some of the domain terms for easier change in the future because we can modify the meaning of the encapsulated term by changing the code inside the factory methods.

Factories help eliminate redundancy

Redundancy in code means that at least two things need to change for the same reason in the same way¹⁴. Usually, it is understood as code duplication, but I consider “conceptual duplication” a better term. For example, the following two methods are not redundant, even though the code seems duplicated (by the way, the following is not an example of good code, just a simple illustration):

1 public int MetersToCentimeters(int value)
2 {
3   return value*100;
4 }
5 
6 public int DollarsToCents(int value)
7 {
8   return value*100;
9 }

As I said, I don’t consider this to be redundancy, because the two methods represent different concepts that would change for different reasons. Even if I was to extract “common logic” from the two methods, the only sensible name I could come up with would be something like MultiplyBy100() which, in my opinion, wouldn’t add any value at all.

Note that so far, we considered four things factories encapsulate about creating objects:

1. Type
2. Rule
3. Global context
4. Terminology

Thus, if factories didn’t exist, all these concepts would leak to surrounding classes (we saw an example when we were talking about encapsulation of global context). Now, as soon as there is more than one class that needs to create instances, these things leak to all of these classes, creating redundancy. In such a case, any change to how instances are created probably means a change to all classes needing to create those instances.

Thankfully, by having a factory – an object that takes care of creating other objects and nothing else – we can reuse the ruleset, the global context and the type-related decisions across many classes without any unnecessary overhead. All we need to do is reference the factory and ask it for an object.

There are more benefits to factories, but I hope I managed to explain why I consider them a pretty darn beneficial concept for a reasonably low cost.

Summary

In the last chapter several chapters, I tried to show you a variety of ways of composing objects together. Don’t worry if you feel overwhelmed, for the most part, just remember to follow the principle of separating use from construction and you should be fine.

The rules outlined here apply to most of the objects in our application. Wait, did I say most of? Not all? So there are exceptions? Yes, there are and we’ll talk about them shortly when I introduce value objects, but first, we need to further examine the influence composability has on our object-oriented design approach.

Interfaces

Some objects are harder to compose with other objects, others are easier. Of course, we are striving for higher composability. Numerous factors influence this. I already discussed some of them indirectly, so time to sum things up and fill in the gaps. This chapter will deal with the role interfaces play in achieving high composability and the next one will deal with the concept of protocols.

Classes vs interfaces

As we said, a sender is composed with a recipient by obtaining a reference to it. Also, we said that we want our senders to be able to send messages to many different recipients. This is, of course, done using polymorphism.

So, one of the questions we have to ask ourselves in our quest for high composability is: on what should a sender depend on to be able to work with as many recipients as possible? Should it depend on classes or interfaces? In other words, when we plug in an object as a message recipient like this:

1 public Sender(Recipient recipient)
2 {
3   this._recipient = recipient;
4 }

Should the Recipient be a class or an interface?

If we assume that Recipient is a class, we can get the composability we want by deriving another class from it and implementing abstract methods or overriding virtual ones. However, depending on a class as a base type for a recipient has the following disadvantages:

1. The recipient class may have some real dependencies. For example, if our Recipient depends on Windows Communication Foundation (WCF) stack, then all classes depending directly on Recipient will indirectly depend on WCF, including our Sender. The more damaging version of this problem is where such a Recipient class does something like opening a network connection in a constructor – the subclasses are unable to prevent it, no matter if they like it or not because a subclass has to call a superclass’ constructor.
2. Recipient’s constructor must be invoked by any class deriving from it, which may be smaller or bigger trouble, depending on what kind of parameters the constructor accepts and what it does.
3. In languages that support single inheritance only, deriving from Recipient class uses up the only inheritance slot, constraining our design.
4. We must make sure to mark all the methods of Recipient class as virtual to enable overriding them by subclasses. otherwise, we won’t have full composability. Subclasses will not be able to redefine all of the Recipient behaviors, so they will be very constrained in what they can do.

As you see, there are some difficulties using classes as “slots for composability”, even if composition is technically possible this way. Interfaces are far better, just because they do not have the above disadvantages.

It is decided then that if a sender wants to be composable with different recipients, it has to accept a reference to a recipient in a form of interface reference. We can say that, by being lightweight and behaviorless, interfaces can be treated as “slots” or “sockets” for plugging in different objects.

As a matter of fact, on UML diagrams, one way to depict a class implementing an interface is by drawing it with a plug. Thus, it seems that the “interface as slot for pluggability” concept is not so unusual.

As you may have already guessed from the previous chapters, we are taking the idea of pluggability and composability to the extreme, making it one of the top priorities.

Events/callbacks vs interfaces – few words on roles

Did I just say that composability is “one of the top priorities” in our design approach? Wow, that’s quite a statement, isn’t it? Unfortunately for me, it also lets you raise the following argument: “Hey, interfaces are not the most extreme way of achieving composability! What about e.g. C# events feature? Or callbacks that are supported by some other languages? Wouldn’t it make the classes even more context-independent and composable, if we connected them through events or callbacks, not interfaces?”

Yes, it would, but it would also strip us from another very important aspect of our design approach that I did not mention explicitly until now. This aspect is: roles. When we use interfaces, we can say that each interface stands for a role for a real object to play. When these roles are explicit, they help design and describe the communication between objects.

Let’s look at an example of how not defining explicit roles can remove some clarity from the design. This is a sample method that sends some messages to two recipients held as interfaces:

 1 //role players:
 2 private readonly Role1 recipient1;
 3 private readonly Role2 recipient2;
 4 
 5 public void SendSomethingToRecipients()
 6 {
 7   recipient1.DoX();
 8   recipient1.DoY();
 9   recipient2.DoZ();
10 }

and we compare it with similar effect achieved using callback invocation:

 1 //callbacks:
 2 private readonly Action DoX;
 3 private readonly Action DoY;
 4 private readonly Action DoZ;
 5 
 6 public void SendSomethingToRecipients()
 7 {
 8   DoX();
 9   DoY();
10   DoZ();
11 }

We can see that in the second case we are losing the notion of which message belongs to which recipient – each callback is standalone from the sender’s point of view. This is unfortunate because, in our design approach, we want to highlight the roles each recipient plays in the communication, to make it readable and logical. Also, ironically, decoupling using events or callbacks can make composability harder. This is because roles tell us which sets of behaviors belong together and thus, need to change together. If each behavior is triggered using a separate event or callback, an overhead is placed on us to remember which behaviors should be changed together, and which ones can change independently.

This does not mean that events or callbacks are bad. It’s just that they are not fit for replacing interfaces – in reality, their purpose is a little bit different. We use events or callbacks not to tell somebody to do something, but to indicate what happened (that’s why we call them events, after all…). This fits well with the observer pattern we already talked about in the previous chapter. So, instead of using observer objects, we may consider using events or callbacks instead (as in everything, there are some tradeoffs for each of the solutions). In other words, events and callbacks have their use in composition, but they are fit for a case so specific, that they cannot be treated as a default choice. The advantage of interfaces is that they bind together messages that represent coherent abstractions and convey roles in the communication. This improves readability and clarity.

Small interfaces

Ok, so we said that the interfaces are “the way to go” for reaching the strong composability we’re striving for. Does merely using interfaces guarantee us that the composability will be strong? The answer is “no” – while using interfaces as “slots” is a necessary step in the right direction, it alone does not produce the best composability.

One of the other things we need to consider is the size of interfaces. Let’s state one thing that is obvious regarding this:

All other things equal, smaller interfaces (i.e. with fewer methods) are easier to implement than bigger interfaces.

The obvious conclusion from this is that if we want to have strong composability, our “slots”, i.e. interfaces, have to be as small as possible (but not smaller – see the previous section on interfaces vs events/callbacks). Of course, we cannot achieve this by blindly removing methods from interfaces, because this would break classes that use these methods e.g. when someone is using an interface implementation like this:

1 public void Process(Recipient recipient)
2 {
3   recipient.DoSomething();
4   recipient.DoSomethingElse();
5 }

It is impossible to remove either of the methods from the Recipient interface because it would cause a compile error saying that we are trying to use a method that does not exist.

So, what do we do then? We try to separate groups of methods used by different senders and move them to separate interfaces so that each sender has access only to the methods it needs. After all, a class can implement more than one interface, like this:

1 public class ImplementingObject
2 : InterfaceForSender1,
3   InterfaceForSender2,
4   InterfaceForSender3
5 { ... }

This notion of creating a separate interface per sender instead of a single big interface for all senders is known as the Interface Segregation Principle¹⁵.

A simple example: separation of reading from writing

Let’s assume we have a class in our application that represents enterprise organizational structure. This application exposes two APIs. The first one serves for notifications about changes of organizational structure by an administrator (so that our class can update its data). The second one is for client-side operations on the organizational data, like listing all employees. The interface for the organizational structure class may contain methods used by both these APIs:

 1 public interface 
 2 OrganizationStructure
 3 {
 4   //////////////////////
 5   //used by administrator:
 6   //////////////////////  
 7   
 8   void Make(Change change);
 9   //...other administrative methods
10   
11   //////////////////////
12   //used by clients:
13   //////////////////////
14   
15   void ListAllEmployees(
16     EmployeeDestination destination);
17   //...other client-side methods  
18 }

However, the administrative API handling is done by a different code than the client-side API handling. Thus, the administrative part has no use of the knowledge about listing employees and vice-versa – the client-side one has no interest in making administrative changes. We can use this knowledge to split our interface into two:

 1 public interface
 2 OrganizationalStructureAdminCommands
 3 {
 4   void Make(Change change);
 5   //... other administrative methods
 6 }
 7 
 8 public interface
 9 OrganizationalStructureClientCommands
10 {
11   void ListAllEmployees(
12     EmployeeDestination destination);
13   //... other client-side methods
14 }

Note that this does not constrain the implementation of these interfaces – a real class can still implement both of them if this is desired:

1 public class InMemoryOrganizationalStructure
2 : OrganizationalStructureAdminCommands,
3   OrganizationalStructureClientCommands
4 {
5   //...
6 }

In this approach, we create more interfaces (which some of you may not like), but that shouldn’t bother us much because, in return, each interface is easier to implement (because the number of methods to implement is smaller than in case of one big interface). This means that composability is enhanced, which is what we want the most.

It pays off. For example, one day, we may get a requirement that all writes to the organizational structure (i.e. the admin-related operations) have to be traced. In such case, all we have to do is to create a proxy class implementing OrganizationalStructureAdminCommands interface, which wraps the original class’ methods with a notification to an observer (that can be either the trace that is required or anything else we like):

 1 public class NotifyingAdminCommands : OrganizationalStructureAdminCommands
 2 {
 3   public NotifyingCommands(
 4     OrganizationalStructureAdminCommands wrapped,
 5     ChangeObserver observer)
 6   {
 7     _wrapped = wrapped;
 8     _observer = observer;
 9   }
10 
11   void Make(Change change)
12   { 
13     _wrapped.Make(change);
14     _observer.NotifyAbout(change);
15   }
16   
17   //...other administrative methods
18 }

Note that when defining the above class, we only had to implement one interface: OrganizationalStructureAdminCommands, and could ignore the existence of OrganizationalStructureClientCommands. This is because of the interface split we did before. If we had not separated interfaces for admin and client access, our NotifyingAdminCommands class would have to implement the ListAllEmployees method (and others) and make it delegate to the original wrapped instance. This is not difficult, but it’s unnecessary effort. Splitting the interface into two smaller ones spared us this trouble.

Interfaces should model roles

In the above example, we split the one bigger interface into two smaller, in reality exposing that the InMemoryOrganizationalStructure class objects can play two roles.

Considering roles is another powerful way of separating interfaces. For example, in the organizational structure we mentioned above, we may have objects of class Employee, but that does not mean this class has to implement an interface called IEmployee or EmployeeIfc of anything like that. Honestly speaking, this is a situation that we may start of with, when we don’t have better ideas yet, but would like to get away from as soon as we can through refactoring. What we would like to do as soon as we can is to recognize valid roles. In our example, from the point of view of the structure, the employee might play a Node role. If it has a parent (e.g. an organization unit) it belongs to, from its perspective it might play a ChildUnit role. Likewise, if it has any children in the structure (e.g. employees he manages), he can be considered their Parent or DirectSupervisor. All of these roles should be modeled using interfaces which Employee class implements:

1 public class Employee : Node, ChildUnit, DirectSupervisor
2 {
3  //...

and each of those interfaces should be given only the methods that are needed from the point of view of objects interacting with a role modeled with this interface.

Interfaces should depend on abstractions, not implementation details

It is tempting to think that every interface is an abstraction by definition. I believe otherwise – while interfaces abstract away the concrete type of the class that implements it, they may still contain some other things not abstracted that are implementation details. Let’s look at the following interface:

1 public interface Basket
2 {
3   void WriteTo(SqlConnection sqlConnection);
4   bool IsAllowedToEditBy(SecurityPrincipal user);
5 }

See the arguments of those methods? SqlConnection is a library object for interfacing directly with an SQL Server database, so it is a very concrete dependency. SecurityPrincipal is one of the core classes of .NET’s authorization library that works with a user database on a local system or in Active Directory. So again, a very concrete dependency. With dependencies like that, it will be very hard to write other implementations of this interface, because we will be forced to drag around concrete dependencies and mostly will not be able to work around that if we want something different. Thus, we may say that these concrete types I mentioned are implementation details exposed in the interface. Thus, this interface is a failed abstraction. It is essential to abstract these implementation details away, e.g. like this:

1 public interface Basket
2 {
3   void WriteTo(ProductOutput output);
4   bool IsAllowedToEditBy(BasketOwner user);
5 }

This is better. For example, as ProductOutput is a higher-level abstraction (most probably an interface, as we discussed earlier) no implementation of the WriteTo method must be tied to any particular storage kind. This means that we have more freedom to develop different implementations of this method. Also, each implementation of the WriteTo method is more useful as it can be reused with different kinds of ProductOutputs.

Another example might be a data interface, i.e. an interface with getters and setters only. Looking at this example:

1 public interface Employee
2 {
3   HumanName Name { get; set; }
4   HumanAge  Age { get; set; }
5   Address Address { get; set; }
6   Money Pay { get; set; }
7   EmploymentStatus EmploymentStatus { get; set; }
8 }

in how many different ways can we implement such an interface? Not many – the only question we can answer differently in different implementations of Employee is: “what is the data storage?”. Everything besides this question is exposed, making this a very poor abstraction. This is similar to what Johnny and Benjamin were battling in the payroll system when they wanted to introduce another kind of employee – a contractor employee. Thus, most probably, a better abstraction would be something like this:

1 public interface Employee
2 {
3   void Sign(Document document);
4   void Send(PayrollReport payrollReport);
5   void Fire();
6   void GiveRaiseBy(Percentage percentage);
7 }

So the general rule is: make interfaces real abstractions by abstracting away the implementation details from them. Only then are you free to create different implementations of the interface that are not constrained by dependencies they do not want or need.

Protocols

You already know that objects are connected (composed) together and communicate through interfaces, just as in IP network. There is one more similarity, that’s as important. It’s protocols. In this section, we will look at protocols between objects and their place on our design approach.

Protocols exist

I do not want to introduce any scientific definition, so let’s just establish an understanding that protocols are sets of rules about how objects communicate with each other.

Really? Are there any rules? Is it not enough the objects can be composed together through interfaces, as I explained in previous sections? Well, no, it’s not enough and let me give you a quick example.

Let’s imagine a class Sender that, in one of its methods, asks Recipient (let’s assume Recipient is an interface) to extract status code from some kind of response object and makes a decision based on that code whether or not to notify an observer about an error:

1 if(recipient.ExtractStatusCodeFrom(response) == -1)
2 {
3   observer.NotifyErrorOccured();
4 }

This design is a bit simplistic but nevermind. Its role is to make a certain point. Whoever the recipient is, it is expected to report an error by returning a value of -1. Otherwise, the Sender (which is explicitly checking for this value) will not be able to react to the error situation appropriately. Similarly, if there is no error, the recipient must not report this by returning -1, because if it does, the Sender will mistakenly recognize this as an error. So, for example, this implementation of Recipient, although implementing the interface required by Sender, is wrong, because it does not behave as Sender expects it to:

 1 public class WrongRecipient : Recipient
 2 {
 3   public int ExtractStatusFrom(Response response)
 4   {
 5     if( /* success */ )
 6     {
 7       return -1; // but -1 is for errors!
 8     }
 9     else
10     {
11       return 1; // -1 should be used!
12     }
13   }
14 }

So as you see, we cannot just write anything in a class implementing an interface, because of a protocol that imposes certain constraints on both a sender and a recipient.

This protocol may not only determine the return values necessary for two objects to interact properly, but it can also determine types of exceptions thrown or the order of method calls. For example, anybody using some kind of connection object would imagine the following way of using the connection: first, open it, then do something with it and close it when finished, e.g.

1 connection.Open();
2 connection.Send(data);
3 connection.Close();

Assuming the above connection is an implementation of Connection interface, if we were to implement it like this:

 1 public class WrongConnection : Connection
 2 {
 3   public void Open()
 4   {
 5     // imagine implementation
 6     // for *closing* the connection is here!!
 7   }
 8 
 9   public void Close()
10   {
11     // imagine implementation for
12     // *opening* the connection is here!!
13   }
14 }

then it would compile just fine but fail badly when executed. This is because the behavior would be against the protocol set between Connection abstraction and its user. All implementations of Connection must follow this protocol.

So, again, there are rules that restrict the way two objects can communicate. Both a sender and a recipient of a message must adhere to the rules, or they will not be able to work together.

The good news is that most of the time, we are the ones who design these protocols, along with the interfaces, so we can design them to be either easier or harder to follow by different implementations of an interface. Of course, we are wholeheartedly for the “easier” part.

Protocol stability

Remember the last story about Johnny and Benjamin when they had to make a design change to add another kind of employees (contractors) to the application? To do that, they had to change existing interfaces and add new ones. This was a lot of work. We don’t want to do this much work every time we make a change, especially when we introduce a new variation of a concept that is already present in our design (e.g. Johnny and Benjamin already had the concept of “employee” and they were adding a new variation of it, called “contractor”).

To achieve this, we need the protocols to be more stable, i.e. less prone to change. By drawing some conclusions from experiences of Johnny and Benjamin, we can say that they had problems with protocols stability because the protocols were:

1. complicated rather than simple
2. concrete rather than abstract
3. large rather than small

Based on the analysis of the factors that make the stability of the protocols bad, we can come up with some conditions under which these protocols could be more stable:

1. protocols should be simple
2. protocols should be abstract
3. protocols should be logical
4. protocols should be small

And some heuristics help us get closer to these qualities:

Craft messages to reflect the sender’s intention

The protocols are simpler if they are designed from the perspective of the object that sends the message, not the one that receives it. In other words, method signatures should reflect the intention of senders rather than the capabilities of recipients.

As an example, let’s look at a code for logging in that uses an instance of an AccessGuard class:

1 accessGuard.SetLogin(login);
2 accessGuard.SetPassword(password);
3 accessGuard.Login();

In this little snippet, the sender must send three messages to the accessGuard object: SetLogin(), SetPassword() and Login(), even though there is no real need to divide the logic into three steps – they are all executed in the same place anyway. The maker of the AccessGuard class might have thought that this division makes the class more “general purpose”, but it seems this is a “premature optimization” that only makes it harder for the sender to work with the accessGuard object. Thus, the protocol that is simpler from the perspective of a sender would be:

1 accessGuard.LoginWith(login, password);

Naming by intention

Another lesson learned from the above example is: setters (like SetLogin and SetPassword in our example) rarely reflect senders’ intentions – more often they are artificial “things” introduced to directly manage object state. This may also have been the reason why someone introduced three messages instead of one – maybe the AccessGuard class was implemented to hold two fields (login and password) inside, so the programmer might have thought someone would want to manipulate them separately from the login step… Anyway, setters should be either avoided or changed to something that reflects the intention better. For example, when dealing with the observer pattern, we don’t want to say: SetObserver(screen), but rather something like FromNowOnReportCurrentWeatherTo(screen).

The issue of naming can be summarized with the following statement: a name of an interface should be assigned after the role that its implementations play and methods should be named after the responsibilities we want the role to have. I love the example that Scott Bain gives in his Emergent Design book¹⁶: if I asked you to give me your driving license number, you might’ve reacted differently based on whether the driving license is in your pocket, or your wallet, or your bag, or in your house (in which case you would need to call someone to read it for you). The point is: I, as a sender of this “give me your driving license number” message, do not care how you get it. I say RetrieveDrivingLicenseNumber(), not OpenYourWalletAndReadTheNumber().

This is important because if the name represents the sender’s intention, the method will not have to be renamed when new classes are created that fulfill this intention in a different way.

Model interactions after the problem domain

Sometimes at work, I am asked to conduct a design workshop. The example I often give to my colleagues is to design a system for order reservations (customers place orders and shop deliverers can reserve who gets to deliver which order). The thing that struck me the first few times I did this workshop was that even though the application was all about orders and their reservation, nearly none of the attendees introduced any kind of Order interface or class with Reserve() method on it. Most of the attendees assume that Order is a data structure and handle reservation by adding it to a “collection of reserved items” which can be imagined as the following code fragment:

1 // order is just a data structure,
2 // added to a collection
3 reservedOrders.Add(order)

While this achieves the goal in technical terms (i.e. the application works), the code does not reflect the domain.

If roles, responsibilities, and collaborations between objects reflect the domain, then any change that is natural in the domain is natural in the code. If this is not the case, then changes that seem small from the perspective of the problem domain end up touching many classes and methods in highly unusual ways. In other words, the interactions between objects become less stable (which is exactly what we want to avoid).

On the other hand, let’s assume that we have modeled the design after the domain and have introduced a proper Order role. Then, the logic for reserving an order may look like this:

1 order.ReserveBy(deliverer);

Note that this line is as stable as the domain itself. It needs to change e.g. when orders are not reserved anymore, or someone other than deliverers starts reserving the orders. Thus, I’d say the stability of this tiny interaction is darn high.

Even in cases when the understanding of the domain evolves and changes rapidly, the stability of the domain, although not as high as usual, is still one of the highest the world around us has to offer.

Another example

Let’s assume that we have a code for handling alarms. When an alarm is triggered, all gates are closed, sirens are turned on and a message is sent to special forces with the highest priority to arrive and terminate the intruder. Any error in this procedure leads to shutting down power in the building. If this workflow is coded like this:

 1 try
 2 {
 3   gates.CloseAll();
 4   sirens.TurnOn();
 5   specialForces.NotifyWith(Priority.High);
 6 } 
 7 catch(SecurityFailure failure)
 8 {
 9   powerSystem.TurnOffBecauseOf(failure);
10 }

Then the risk of this code changing for other reasons than the change of how domain works (e.g. we do not close the gates anymore but activate laser guns instead) is small. Thus, interactions that use abstractions and methods that directly express domain rules are more stable.

So, to sum up – if a design reflects the domain, it is easier to predict how a change of domain rules will affect the design. This contributes to the maintainability and stability of the interactions and the design as a whole.

Message recipients should be told what to do, instead of being asked for information

Let’s say we are paying an annual income tax yearly and are too busy (i.e. have too many responsibilities) to do this ourselves. Thus, we hire a tax expert to calculate and pay the taxes for us. He is an expert on paying taxes, knows how to calculate everything, where to submit it, etc. but there is one thing he does not know – the context. In other words, he does not know which bank we are using or what we have earned this year that we need to pay the tax for. This is something we need to give him.

Here’s the deal between us and the tax expert summarized as a table:

It is us who hire the expert and us who initiate the deal, so we need to provide the context, as seen in the above table. If we were to model this deal as an interaction between two objects, it could e.g. look like this:

1 taxExpert.PayAnnualIncomeTax(
2   ourIncomeDocuments,
3   ourBank);

One day, our friend, Joan, tells us she needs a tax expert as well. We are happy with the one we hired, so we recommend him to Joan. She has her own income documents, but they are functionally similar to ours, just with different numbers here and there and maybe some different formatting. Also, Joan uses a different bank, but interacting with any bank these days is almost identical. Thus, our tax expert knows how to handle her request. If we model this as interaction between objects, it may look like this:

1 taxExpert.PayAnnualIncomeTax(
2   joansIncomeDocuments,
3   joansBank);

Thus, when interacting with Joan, the tax expert can still use his abilities to calculate and pay taxes the same way as in our case. This is because his skills are independent of the context.

Another day, we decide we are not happy anymore with our tax expert, so we decide to make a deal with a new one. Thankfully, we do not need to know how tax experts do their work – we just tell them to do it, so we can interact with the new one just as with the previous one:

1 //this is the new tax expert,
2 //but no change to the way we talk to him:
3 
4 taxExpert.PayAnnualIncomeTax(
5   ourIncomeDocuments,
6   ourBank);

This small example should not be taken literally. Social interactions are far more complicated and complex than what objects usually do. But I hope I managed to illustrate with it an important aspect of the communication style that is preferred in object-oriented design: the Tell Don’t Ask heuristic.

Tell Don’t Ask means that each object, as an expert in its job, handles it well while delegating other responsibilities to other objects that are experts in their respective jobs and provide them with all the context they need to achieve the tasks it wants them to do as parameters of the messages it sends to them.

This can be illustrated with a generic code pattern:

1 recipient.DoSomethingForMe(allTheContextYouNeedToKnow);

This way, a double benefit is gained:

1. Our recipient (e.g. taxExpert from the example) can be used by other senders (e.g. pay tax for Joan) without needing to change. All it needs is a different context passed inside a constructor and messages.
2. We, as senders, can easily use different recipients (e.g. different tax experts that do the task they are assigned differently) without learning how to interact with each new one.

If you look at it, as much as bank and documents are a context for the tax expert, the tax expert is a context for us. Thus, we may say that a design that follows the Tell Don’t Ask principle creates classes that are context-independent.

This has a very profound influence on the stability of the protocols. As much as objects are context-independent, they (and their interactions) do not need to change when the context changes.

Again, quoting Scott Bain, “what you hide, you can change”. Thus, telling an object what to do requires less knowledge than asking for data and information. Again using the driver license metaphor: I may ask another person for a driving license number to make sure they have the license and that it is valid (by checking the number somewhere). I may also ask another person to provide me with directions to the place I want the first person to drive. But isn’t it easier to just tell “buy me some bread and butter”? Then, whoever I ask, has the freedom to either drive or walk (if they know a good store nearby) or ask yet another person to do it instead. I don’t care as long as tomorrow morning, I find the bread and butter in my fridge.

All of these benefits are, by the way, exactly what Johnny and Benjamin were aiming at when refactoring the payroll system. They went from this code, where they asked employee a lot of questions:

1 var newSalary 
2   = employee.GetSalary() 
3   + employee.GetSalary() 
4   * 0.1;
5 employee.SetSalary(newSalary);

to this design that told employee do do its job:

1 employee.EvaluateRaise();

This way, they were able to make this code interact with both RegularEmployee and ContractorEmployee the same way.

This guideline should be treated very, very seriously and applied in almost an extreme way. There are, of course, few places where it does not apply and we’ll get back to them later.

Oh, I almost forgot one thing! The context that we are passing is not necessarily data. It is even more frequent to pass around behavior than to pass data. For example, in our interaction with the tax expert:

1 taxExpert.PayAnnualIncomeTax(
2   ourIncomeDocuments,
3   ourBank);

The Bank class is probably not a piece of data. Rather, I would imagine the Bank to implement an interface that looks like this:

1 public interface Bank
2 {
3   void TransferMoney(
4     Amount amount, 
5     AccountId sourceAccount,
6     AccountId destinationAccount); 
7 }

So as you can see, this Bank exposes behavior, not data, and it follows the Tell Don’t Ask style as well (it does something well and takes all the context it needs from outside).

Where Tell Don’t Ask does not apply

As I mentioned earlier, there are places where Tell Don’t Ask does not apply. Here are some examples off the top of my head:

1. Factories – these are objects that produce other objects for us, so they are inherently “pull-based” – they are always asked to deliver objects.
2. Collections – they are merely containers for objects, so all we want from them is adding objects and retrieving objects (by index, by a predicate, using a key, etc.). Note, however, that when we write a class that wraps a collection inside, we want this class to expose interface shaped in a Tell Don’t Ask manner.
3. Data sources, like databases – again, these are storage for data, so it is more probable that we will need to ask for this data to get it.
4. Some APIs accessed via network – while it is good to use as much Tell Don’t Ask as we can, web APIs have one limitation – it is hard or impossible to pass behaviors as polymorphic objects through them. Usually, we can only pass data.
5. So-called “fluent APIs”, also called “internal domain-specific languages”¹⁷

Even in cases where we obtain other objects from a method call, we want to be able to apply Tell Don’t Ask to these other objects. For example, we want to avoid the following chain of calls:

1 Radio radio = radioRepository().GetRadio(12);
2 var userName = radio.GetUsers().First().GetName();
3 primaryUsersList.Add(userName);

This way we make the communication tied to the following assumptions:

1. Radio has many users
2. Radio must have at least one user
3. Each user must have a name
4. The name is not null

On the other hand, consider this implementation:

1 Radio radio = radioRepository().GetRadio(12);
2 radio.AddPrimaryUserNameTo(primaryUsersList);

It does not have any of the weaknesses of the previous example. Thus, it is more stable in the face of change.

Most of the getters should be removed, return values should be avoided

The above-stated guideline of “Tell Don’t Ask” has a practical implication of getting rid of (almost) all the getters. We did say that each object should stick to its work and tell other objects to do their work, passing context to them, didn’t we? If so, then why should we “get” anything from other objects?

For me, the idea of “no getters” was very extreme at first, but in a short time, I learned that this is in fact how I am supposed to write object-oriented code. I started learning to program using procedural languages such as C, where a program was divided into procedures or functions and data structures. Then I moved on to object-oriented languages that had far better mechanisms for abstraction, but my style of coding didn’t change much. I would still have procedures and functions, just divided into objects. I would still have data structures, but now more abstract, e.g. objects with setters, getters, and some query methods.

But what alternatives do we have? Well, I already introduced Tell Don’t Ask, so you should know the answer. Even though you should, I want to show you another example, this time specifically about getters and setters.

Let’s say that we have a piece of software that handles user sessions. A session is represented in code using a Session class. We want to be able to do three things with our sessions: display them on the GUI, send them through the network and persist them. In our application, we want each of these responsibilities handled by a separate class, because we think it is good if they are not tied together.

So, we need three classes dealing with data owned by the session. This means that each of these classes should somehow obtain access to the data. Otherwise, how can this data be e.g. persisted? It seems we have no choice and we have to expose it using getters.

Of course, we might re-think our choice of creating separate classes for sending, persistence, etc. and consider a choice where we put all this logic inside a Session class. If we did that, however, we would make a core domain concept (a session) dependent on a nasty set of third-party libraries (like a particular GUI library), which would mean that e.g. every time some GUI displaying concept changes, we will be forced to tinker in core domain code, which is pretty risky. Also, if we did that, the Session would be hard to reuse, because every place we would want to reuse this class, we would need to take all these heavy libraries it depends on with us. Plus, we would not be able to e.g. use Session with different GUI or persistence libraries. So, again, it seems like our (not so good, as we will see) only choice is to introduce getters for the information pieces stored inside a session, like this:

1 public interface Session
2 {
3   string GetOwner();
4   string GetTarget();
5   DateTime GetExpiryTime();
6 }

So yeah, in a way, we have decoupled Session from these third-party libraries and we may even say that we have achieved context-independence as far as Session itself is concerned – we can now pull all its data e.g. in a GUI code and display it as a table. The Session does not know anything about it. Let’s see:

1 // Display sessions as a table on GUI
2 foreach(var session in sessions)
3 {
4   var tableRow = TableRow.Create();
5   tableRow.SetCellContentFor("owner", session.GetOwner());
6   tableRow.SetCellContentFor("target", session.GetTarget());
7   tableRow.SetCellContentFor("expiryTime", session.GetExpiryTime());
8   table.Add(tableRow);
9 }

It seems we solved the problem by separating the data from the context it is used in and pulling data to a place that has the context, i.e. knows what to do with this data. Are we happy? We may be unless we look at how the other parts look like – remember that in addition to displaying sessions, we also want to send them and persist them. The sending logic looks like this:

1 //part of sending logic
2 foreach(var session in sessions)
3 {
4   var message = SessionMessage.Blank();
5   message.Owner = session.GetOwner();
6   message.Target = session.GetTarget();
7   message.ExpiryTime = session.GetExpiryTime();
8   connection.Send(message);
9 }

and the persistence logic like this:

1 //part of storing logic
2 foreach(var session in sessions)
3 {
4   var record = Record.Blank();
5   dataRecord.Owner = session.GetOwner();
6   dataRecord.Target = session.GetTarget();
7   dataRecord.ExpiryTime = session.GetExpiryTime();
8   database.Save(record);
9 }

See anything disturbing here? If no, then imagine what happens when we add another piece of information to the Session, say, a priority. We now have three places to update and we have to remember to update all of them every time. This is called “redundancy” or “asking for trouble”. Also, the composability of these three classes is pretty bad, because they will have to change a lot only because data in a session changes.

The reason for this is that we made the Session class effectively a data structure. It does not implement any domain-related behaviors, it just exposes data. There are two implications of this:

1. This forces all users of this class to define session-related behaviors on behalf of the Session, meaning these behaviors are scattered all over the place¹⁸. If one is to make a change to the session, they must find all related behaviors and correct them.
2. As a set of object behaviors is generally more stable than its internal data (e.g. a session might have more than one target one day, but we will always be starting and stopping sessions), this leads to brittle interfaces and protocols – certainly the opposite of what we are striving for.

Bummer, this solution is pretty bad, but we seem to be out of options. Should we just accept that there will be problems with this implementation and move on? Thankfully, we don’t have to. So far, we have found the following options to be troublesome:

1. The Session class containing the display, store and send logic, i.e. all the context needed – too much coupling to heavy dependencies.
2. The Session class to expose its data via getters, so that we may pull it where we have enough context to know how to use it – communication is too brittle and redundancy creeps in (by the way, this design will also be bad for multithreading, but that’s something for another time).

Thankfully, we have a third alternative, which is better than the two we already mentioned. We can just pass the context into the Session class. “Isn’t this just another way to do what we outlined in point 1? If we pass the context in, isn’t Session still coupled to this context?”, you may ask. The answer is: not necessarily because we can make the Session class depend on interfaces only instead of the real thing to make it context-independent enough.

Let’s see how this plays out in practice. First, let’s remove those getters from the Session and introduce a new method called DumpInto() that will take a Destination interface implementation as a parameter:

1 public interface Session
2 {
3   void DumpInto(Destination destination);
4 }

The implementation of Session, e.g. a RealSession can pass all fields into this destination like so:

 1 public class RealSession : Session
 2 {
 3   //...
 4 
 5   public void DumpInto(Destination destination)
 6   {
 7     destination.AcceptOwner(this.owner);
 8     destination.AcceptTarget(this.target);
 9     destination.AcceptExpiryTime(this.expiryTime);
10     destination.Done();
11   }
12 
13   //...
14 }

And the looping through sessions now looks like this:

1 foreach(var session : sessions)
2 {
3   session.DumpInto(destination);
4 }

In this design, RealSession itself decides which parameters to pass and in what order (if that matters) – no one is asking for its data. This DumpInto() method is fairly general, so we can use it to implement all three mentioned behaviors (displaying, persistence, sending), by creating an implementation for each type of destination, e.g. for GUI, it might look like this:

 1 public class GuiDestination : Destination
 2 {
 3   private TableRow _row;
 4   private Table _table;
 5   
 6   public GuiDestination(Table table, TableRow row)
 7   {
 8     _table = table;
 9     _row = row;
10   }
11 
12   public void AcceptOwner(string owner)
13   {
14     _row.SetCellContentFor("owner", owner);
15   }
16 
17   public void AcceptTarget(string target)
18   {
19     _row.SetCellContentFor("target", target);
20   }
21 
22   public void AcceptExpiryTime(DateTime expiryTime)
23   {
24     _row.SetCellContentFor("expiryTime", expiryTime);
25   }
26 
27   public void Done()
28   {
29     _table.Add(_row);
30   }
31 }

The protocol is now more stable as far as the consumers of session data are concerned. Previously, when we had the getters in the Session class:

1 public class Session
2 {
3   string GetOwner();
4   string GetTarget();
5   DateTime GetExpiryTime();
6 }

the getters had to return something. So what if we had sessions that could expire and decided we want to ignore them when they do (i.e. do not display, store, send or do anything else with them)? In case of the “getter approach” seen in the snippet above, we would have to add another getter, e.g. called IsExpired() to the session class and remember to update each consumer the same way – to check the expiry before consuming the data… you see where this is going, don’t you? On the other hand, with the current design of the Session interface, we can e.g. introduce a feature where the expired sessions are not processed at all in a single place:

 1 public class TimedSession : Session
 2 {
 3   //...
 4 
 5   public void DumpInto(Destination destination)
 6   {
 7     if(!IsExpired())
 8     {
 9       destination.AcceptOwner(this.owner);
10       destination.AcceptTarget(this.target);
11       destination.AcceptExpiryTime(this.expiryTime);
12       destination.Done();
13     }
14   }
15 
16   //...
17 }

and there is no need to change any other code to get this working¹⁹.

Another advantage of designing/making Session to not return anything from its methods is that we have more flexibility in applying patterns such as proxy and decorator to the Session implementations. For example, we can use proxy pattern to implement hidden sessions that are not displayed/stored/sent at all, but at the same time behave like another session in all the other cases. Such a proxy forwards all messages it receives to the original, wrapped Session object, but discards the DumpInto() calls:

 1 public class HiddenSession : Session
 2 {
 3   private Session _innerSession;
 4 
 5   public HiddenSession(Session innerSession)
 6   {
 7     _innerSession = innerSession;
 8   }
 9 
10   public void DoSomething()
11   {
12     // forward the message to wrapped instance:
13     _innerSession.DoSomething();
14   }
15 
16   //...
17 
18   public void DumpInto(Destination destination)
19   {
20     // discard the message - do nothing
21   }
22 
23   //...
24 }

The clients of this code will not notice this change at all. When we are not forced to return anything, we are more free to do as we like. Again, “tell, don’t ask”.

Protocols should be small and abstract

I already said that interfaces should be small and abstract, so am I not just repeating myself here? The answer is: there is a difference between the size of protocols and the size of interfaces. As an extreme example, let’s take the following interface:

1 public interface Interpreter
2 {
3   public void Execute(string command);
4 }

Is the interface small? Of course! Is it abstract? Well, kind of, yes. Tell Don’t Ask? Sure! But let’s see how it’s used by one of its collaborators:

 1 public void RunScript()
 2 {
 3   _interpreter.Execute("cd dir1");
 4   _interpreter.Execute("copy *.cs ../../dir2/src");
 5   _interpreter.Execute("copy *.xml ../../dir2/config");
 6   _interpreter.Execute("cd ../../dir2/");
 7   _interpreter.Execute("compile *.cs");
 8   _interpreter.Execute("cd dir3");
 9   _interpreter.Execute("copy *.cs ../../dir4/src");
10   _interpreter.Execute("copy *.xml ../../dir4/config");
11   _interpreter.Execute("cd ../../dir4/");
12   _interpreter.Execute("compile *.cs");
13   _interpreter.Execute("cd dir5");
14   _interpreter.Execute("copy *.cs ../../dir6/src");
15   _interpreter.Execute("copy *.xml ../../dir6/config");
16   _interpreter.Execute("cd ../../dir6/");
17   _interpreter.Execute("compile *.cs");
18 }

The point is: the protocol is neither abstract nor small. Thus, making implementations of an interface that is used as such can be pretty painful.

Summary