Microsoft .NET Architecting Applications for the Enterprise, Second Edition (2014)

---

Tell, don’t ask

Overall, Tell-Don’t-Ask is the inspiring principle of object modeling. At the foundation of OOP, there was Stroustrup’s idea of creating software entities that could incorporate data and expose some behavior. That’s precisely the point behind Tell-Don’t-Ask.

When designing an interface, avoid asking for data to be processed in some outermost logical container; instead, tell the interface to perform some action on some explicit data. Bundling together data and behavior helps you with modeling because it more closely represents the observed reality. To fully make sense of Tell-Don’t-Ask, consider the following everyday scenario:

Your significant other asks something along the lines of this: “Honey, what are you doing right now? Are you busy?”

Your significant other plays the role of the outermost logical container and is planning to orchestrate you in some process she’s eager to arrange. The point is that you might or might not be able (or willing) to do the task. But you are requested to provide data about your internal state without knowing the reason that data is required. Your answer might lead your significant other to command you to assist regardless of your situation or to find an alternate way of accomplishing the task.

Wouldn’t it be simpler and easier for everybody if she just told you what to do?

Honey, I need you to take the trash out.

The significant other—the orchestrator—only needs to keep track of whether the task has been accomplished or not in the allowed time. All the details of how it happens are delegated to and encapsulated in the object receiving the command.

Use of patterns

When facing a problem, a developer will certainly draw from the well of personal experience for any solutions to similar problems that worked in the past. Such building blocks are nothing more than hints and represent the skeleton of a solution. However, these same building blocks can become more refined day after day and generalized after each usage to become applicable to a wider range of problems and scenarios. Such building blocks might not provide a direct solution, but they usually help you to find your (right) way. And using them is usually more effective and faster than starting from scratch.

These building blocks are known as patterns.

The word pattern is one of those overloaded terms that morphed from its common usage to assume a specific meaning in computer science. According to the dictionary, a pattern is a template or model that can be used to generate things—all kinds of things. In computer science, we use patterns in design solutions at two levels: implementation and architecture.

What’s a design pattern, exactly?

We software professionals can attribute the concept of design patterns to an architect—a real architect, not a software architect. In the late 1970s, Christopher Alexander developed a pattern language with the purpose of letting individuals express their innate sense of design through a sort of informal grammar. From his work, here’s the definition of a pattern:

Each pattern describes a problem which occurs over and over again in our environment, and then describes the core solution to that problem, in such a way that you can use the solution a million times over, without ever doing it the same way twice.

Nicely enough, although the definition was not written with software development in mind, it applies perfectly to that. So what’s a design pattern?

A design pattern is a known and well-established core solution applicable to a family of concrete problems that might show up during implementation. A design pattern is a core solution and, as such, it might need adaptation to a specific context. This feature becomes a major strength when you consider that, in this way, the same pattern can be applied many times in many slightly different scenarios.

Design patterns are not created in a lab; quite the reverse. They originate from the real world and from the direct experience of developers and architects. You can think of a design pattern as a package that includes the description of a problem, a list of actors participating in the problem, and a practical solution.

The primary reference for design patterns is GoF. Another excellent reference we want to recommend is Pattern-Oriented Software Architecture by Frank Buschmann et al. (Wiley, 1996).

How to work with design patterns

Here is a list of what design patterns are not:

Design patterns are not the verb and should never be interpreted dogmatically.

Design patterns are not Superman and will never magically pop up to save a project in trouble.

Design patterns are neither the dark side nor the light side of the Force. They might be with you, but they won’t provide you with any special extra power.

Design patterns are just helpful, and that should be enough.

You don’t choose a design pattern; the most appropriate design pattern normally emerges out of your refactoring steps. We could say that the pattern is buried under your classes, but digging it out is entirely up to you.

The wrong way to deal with design patterns is by going through a list of patterns you might find in books and matching them to the problem. Instead, it works the other way around. You have a problem and you have to match the problem to the pattern. How can you do that? It’s quite simple to explain, but it’s not so easy to apply.

You have to understand the problem and generalize it.

If you can take the problem back to its roots and get the gist of it, you’ll probably find a tailor-made pattern just waiting for you. Why is this so? Well, if you really reached the root of the problem, chances are that someone else did the same in the past 20 years (the period during which design patterns became more widely used). So the solution is probably just there for you to read and apply.

This observation prompts us to mention the way in which all members of our teams use books on design patterns. (By the way, there are always plenty of such books scattered throughout the office.) Design patterns books are an essential tool. But we never read such books. We use them, instead, like cookbooks.

What we normally do is stop reading after the first few pages precisely where most books list the patterns they cover in detail inside. Next, we put the book aside and possibly within reach. Whenever we encounter a problem, we try to generalize it, and then we flip through the pages of the book to find a pattern that possibly matches it. We find one much more often than not. And if we don’t, we repeat the process in an attempt to come to a better generalization of the problem.

When we find the pattern, we start working on its adaptation to our context. This often requires refactoring of the code which, in turn, might lead to a more appropriate pattern. And the loop goes on.

Where’s the value in patterns, exactly?

Many people would agree in principle that there’s plenty of value in design patterns. Fewer people, though, would be able to indicate what the value is and where it can be found. Using design patterns, per se, doesn’t make your solution more valuable. What really matters, at the end of the day, is whether or not your solution works and meets requirements.

Armed with requirements and design principles, you are up to the task of solving a problem. On your way to the solution, though, a systematic application of design principles to the problem sooner or later takes you into the immediate neighborhood of a known design pattern. That’s a certainty because, ultimately, patterns are solutions that others have already found and catalogued.

At that point, you have a solution with some structural likeness to a known design pattern. It is up to you, then, to determine whether an explicit refactoring to that pattern will bring some added value to the solution. Basically, you have to decide whether or not the known pattern you found represents a further, and desirable, refinement of your current solution. Don’t worry if your solution doesn’t match a pattern. It means that you have a solution that works and you’re happy with that. You’re just fine. You never want to change a winning team!

In summary, patterns might be an end when you refactor according to them, and they might be a means when you face a problem that is clearly resolved by a particular pattern. Patterns are not an added value for your solution, but they are valuable for you as an architect or a developer looking for a solution.

Refactoring

Refactoring is the discipline of restructuring existing code in such a way that the external behavior remains unaltered. You refactor your code not because it doesn’t work but just to better address some nonfunctional attribute—such as readability, maintainability, testability, or extensibility—or even to improve performance.

Even though the term refactoring might lead some people to think of sophisticated practices, for the most part refactoring is the continuous performance of a few micro-operations. In addition, some of these operations are mechanically performed for you by ad hoc tools like ReSharper. Here are a few common refactoring operations:

Extract method Move a bunch of lines to a newly created method, thus making the original method shorter and promoting readability and code reuse.

Extract interface Turn the public methods in an existing class into a newly created interface. In this way, you promote interface programming and lower coupling between modules.

Encapsulate field Wrap a field in a class with a pair of getter and setter methods.

Refactoring also means renaming classes and methods throughout the codebase and moving classes to different namespaces. This is a delicate activity where code assistant tools really shine; without an automatic tool, renaming can really be painful. But renaming is critical to improving code readability, as you’ll see in more detail in the next chapter.

In the end, refactoring can be summarized in two points. One is continuous code editing improves readability and design. The other is performing more ambitious restructuring aimed at making the existing code adhere to a specific pattern.

Defensive programming

As Murphy used to say, if something can go wrong, it will. And Murphy was not a software engineer. As developers, we know the pattern very well. We mentioned the Ariadne 5 disaster in Chapter 1, “Architects and architecture today.” It all happened because developers didn’t write their code defensively. Defensive programming is about making the software work in a predictable manner in spite of unexpected inputs.

Concretely speaking, defensive programming is all about carefully checking input data in each and every method you have and making it clear through documentation and other means what each method actually produces. This can be done in a couple of ways—an old way and a more modern and effective way.

The If-Then-Throw pattern

An old but good practice of software development recommends that you place at the top of each method—before any significant behavior takes place—a barrier of conditional statements. Each conditional statement checks a different condition that input values must verify. If the condition isn’t verified, the code throws an exception. This pattern is often referred to as If-Then-Throw.

To be honest, we’ve heard If-Then-Throw labeled as a pattern, but we don’t think a formal definition exists for that. Maybe we should simply refer to it as a practice? Anyway, it’s not rocket science and is mostly about common sense. The idea is that the first lines of a method should be devoted to checking the validity of method arguments. In this way, if any invalid data is passed, you fail as quickly as possible without proceeding any further in the code. The application of this pattern is particularly important for constructors because it ensures that the state of the object is valid. You don’t need to use the pattern for private methods because these methods can be called only from the class itself and likely from the same author. Here’s an example: you pass every argument through a Boolean expression that ascertains whether the value is acceptable. If it is not, you just throw an exception:

public class Match()
{
public Match(String id, String home, String visitors)
{
// If-Then-Throw implementation
if (String.IsNullOrWhitespace(id))
throw new ArgumentException("id");
if (String.IsNullOrWhitespace(home))
throw new ArgumentException("home");
if (String.IsNullOrWhitespace(visitors))
throw new ArgumentException("visitors");

...
}

...
}

Extensive use of the If-Then-Throw pattern serves the purpose of evaluating the preconditions for a public method to run. It says nothing about the output generated and invariant conditions. At the end of the day, the If-Then-Throw pattern is a useful little thing especially if you apply it extensively to nearly any piece of data you receive from outbound calls.

For stricter and more effective control over the behavior of a class as a whole, you might want to look into something that Bertrand Meyer called Design by Contract. Design by Contract is an approach to programming based on the idea that each piece of software has a contract in which it formally describes what it expects and what it provides. The If-Then-Throw pattern nearly covers the first part of the contract, but it entirely lacks the second part.

Software contracts

Design by Contract describes the interaction between software components as a contract, where obligations and benefits are clearly expressed and enforced. Design by Contract isn’t natively supported in any mainstream programming language. However, frameworks exist to let you taste flavors of it in commonly used languages such as Java, Perl, Ruby, JavaScript and, of course, the Microsoft .NET Framework languages. In .NET, you create software contracts via the Code Contracts library added to the .NET Framework 4.

In the implementation of a software contract—regardless of the syntax details—any time you write a class method, you should be sure you can answer the following questions:

Under which conditions can the method be invoked?

Which conditions are verified after the method terminates?

Which conditions do not change before and after the method execution?

These three questions are also known, respectively, as preconditions, postconditions, and invariants. Let’s go a bit deeper into software contracts using the .NET implementation—Code Contracts—as a reference.

Preconditions

Preconditions refer to the Boolean conditions that must be verified for the method to start its execution. Typically, preconditions set conditions on input parameters and the current state of the class that exposes the method. Conceptually, preconditions are the same as the If-Then-Throw pattern. Have a look at the following code excerpt. It comes from a class—named Match—that describes any team sport game with periods (for example, basketball, football, water polo, and so on).

public Match(String id, String team1, String team2)
{
Contract.Requires<ArgumentException>(id.IsAlphaNumeric(IdLength, IdLength));
Contract.Requires<ArgumentException>(!team1.IsNullOrWhitespace());
Contract.Requires<ArgumentException>(!team2.IsNullOrWhitespace());
...
}
public Match EndPeriod()
{
Contract.Requires<ArgumentException>(IsInProgress());
Contract.Requires<ArgumentException>(IsBallInPlay);
Contract.Ensures(!IsBallInPlay);

IsBallInPlay = false;
if (CurrentPeriod == LastPeriod)
Finish();
return this;
}

The constructor expressly requires that its id argument be alphanumeric and of the specified length. If it is not, it throws an ArgumentException exception. Similarly, team names must be neither empty nor null; otherwise, the same exception is thrown. Contract.Requires<T> is the .NET way to express a precondition and bind it to a custom exception if the condition fails.

There a few interesting things to notice here. First and foremost, you express Boolean guards in the positive way, whereas you have them in the negated form if you opt for the If-Then-Throw pattern. This works also as a form of documentation and as a guide for testers. Second, the syntax is particularly compact and custom, and if they are aptly named, functions can be used to keep the readability of the code high.

Preconditions on the constructor check only input data, but if you look at the method EndPeriod, you see that preconditions can also be applied to the internal state of the object. You can’t call a period if game is not in progress and the ball is not in play.

Postconditions

Postconditions refer to the output generated by the method and the changes produced to the state of the object. A postcondition is a Boolean condition that holds true upon exit from the method. Managing postconditions manually can be cumbersome, but .NET Code Contracts really makes it a piece of cake.

Here’s a short but illustrative example: the method Sum of a calculator class. Without preconditions, the method looks like this:

public Int32 Sum(Int32 x, Int32 y)
{
// Shortcut exit (optimizing 2*x)
if (x == y)
return x << 1;

// Perform the operation and return
var result = x + y;
return result;
}

The method has two exit points. If you want to manually evaluate a postcondition, you need to save somewhere the value being returned, pass it by the Boolean evaluator, and then decide whether to throw or return. Here’s what the final code might look like:

public Int32 Sum(Int32 x, Int32 y)
{
// Shortcut exit
if (x == y)
{
// Perform the operation
var temp = x << 1;

// Evaluate postcondition
if (temp <0)
throw new ArgumentException();

return temp;
}

// Perform the operation
var result = x + y;

// Evaluate postcondition
if (result <0)
throw new ArgumentException();

return result;
}

Using Code Contracts the resulting code is surprisingly clean:

public Int32 Sum(Int32 x, Int32 y)
{
Contract.Ensures(Contract.Result<Int32>() >= 0);

if (x == y)
return x << 1;

var result = x + y;
return result;
}

The Ensures method captures the value being returned and ensures it is not negative; if the value is negative, the method throws a ContractFailedException exception.

Invariants

Invariants refer to a Boolean condition involving members of the class that do not change during the execution of any public methods, including constructors and setters. Invariants are used in all those scenarios where it is essential to avoid leaving objects in a logically inconsistent state. Have a look at the sample News class:

public class News
{
public String Title {get; set;}
public String Body {get; set;}

[ContractInvariantMethod]
private void ObjectInvariant()
{
Contract.Invariant(!String.IsNullOrEmpty(Title));
Contract.Invariant(!String.IsNullOrEmpty(Body));
}
}

The Invariant method specifies that neither Title nor Body can be empty or null. Expand this to any set of business rules for a domain class—you have an easy way to ensure that your objects are always in a valid state. If some code that uses News sets, say, Title to null, immediately an exception for a contract violation will be thrown. More importantly, you don’t have to write a single line of code to check invariants after any call of a public method. That’s the magic of the .NET Framework Code Contracts implementation.