ploeh blog danish software design

This is the first post in a series of posts about the String Calculator kata done with AutoFixture.

This screencast sets up the Visual Studio projects and completes the first exercise of the kata.

Next exercise

If you liked this screencast, you may also like my Pluralsight course Outside-In Test-Driven Development.

Comments

This post introduces the String Calculator kata done with AutoFixture.

A couple of weeks ago, at the Warm Crocodile conference in Copenhagen, Roy Osherove and I talked about AutoFixture and his String Calculator kata, and I decided to do the kata with AutoFixture 3 and make a series of screencasts out of it.

This series makes no particular attempt at explaining what AutoFixture is, so you might want to first acquaint yourself with some basics, such as the theory of Anonymous Variables, Derived Values, Equivalence Classes, and Constrained Non-Determinism. It might also be a good idea to understand how AutoFixture integrates with xUnit.net.

The following screencasts are available:

1. Exercise 1
2. Exercise 2
3. Exercise 3
4. Exercise 4
5. Exercise 5
6. Exercise 6
7. Exercise 7
8. Exercise 8
   

As a general note, I didn't focus much on refactoring in this exercise, as I didn't feel the complexity of the solution required it.

If you like these screencasts, you may also like my Pluralsight course Outside-In Test-Driven Development.

Comments

This article discusses developer productivity tools.

Once in a while I get into a heated discussion about the merits and demerits of ReSharper. As these discussions usually happen on Twitter, the 140 character limit isn't conducive to a nuanced debate. That's what I want to start here, not a rant.

This is not going to be an attack on ReSharper. In fact, I don't have a stronger opinion on ReSharper than any other 'productivity tool', but I more often get dragged into discussions about ReSharper than, say, JustCode or CodeRush. I guess it's because more people feel passionate about ReSharper.

In fact, I'm going to expand this discussion to a wider range of 'productivity tools', such as (but not limited to)

• ReSharper
• JustCode
• CodeRush
• Productivity Power Tools
• Visual Studio

Why are we even having this discussion? #

The only 'productivity tool' I currently use is Visual Studio 2012, and even that makes me uneasy. That's just my personal preference, you might say, and there's a partial truth in that. However, I'm not writing this to defend myself. Rather, I'm writing because I think you need to be aware of the issues presented here. It might make you a better developer if I can get you to actively and consciously consider a choice you may have taken for granted.

How do I even get dragged into these Twitter flame fests? Why do people even care whether or not I use a particular 'productivity tool'? First of all, I can't claim myself innocent of occasionally trolling - I just get a kick out of yanking that particular chain. There's a reason for that, and it's not just to be mischievous. I want you to reflect on your choice of tools. Don't just drink the Cool Aid.

Still, there's a deeper, more rational reason why some people care what I do: I do give a lot of presentations about code, and during those presentations I write a lot of code. Whenever I give a talk where I code live, I always rehearse a lot and use specialized code snippets in order not to bore the audience with trivial coding. Here's an example where during the talk, someone tweeted to complain that I didn't use ReSharper. However, the purpose of giving a talk about code isn't to produce the code in the fastest possible time. The purpose is to teach code. If I code too slowly, the audience may fall asleep, but if I go too fast, no one is going to learn anything. I'm just not convinced that in this particular case, the use of a 'productivity tool' is inherently better.

Can you even live without this or that productivity tool? #

The most common reaction I get whenever people hear that I don't use their favorite 'productivity tool' is one of disbelief.

• omg why? How can do without #resharper?
• You're seriously missing out. Visual Studio is completely useless without ReSharper, imho.
• but how will you work then? Bare bone vs is soo poor compared to just about any ide
• Without #resharper my productivity drops by 50%, I'm amazed that you can manage without it
• I don't understand why you avoid ReSharper.
• hmm.. R# is good for navigating around. Shortcuts to follow application flow, up and down. How do you do that without r#?

What's my beef with productivity tools? It's much deeper than a dislike for any particular tool. Charles Petzold already described his concern about Visual Studio in 2005 in a great talk titled Does Visual Studio Rot the Mind?. It's a long read, but definitely worth your while. You should go read it now.

In case you didn't want to take the time to read that article (but then: you're already reading this lengthy article), here's the gist of it: Via IntelliSense, code generation, Wizards and drag and drop, Visual Studio assists us, but it also pushes us towards writing (or not writing) code in a particular way. It railroads us.

Does it make us more productive? I don't even know how to measure developer productivity, so I can't answer that. Do we learn while coding like that? Not much, I'd say.

While Visual Studio is, in many ways, an impressive and extremely useful piece of software, it also concerns me that I'm so dependent on it. To learn new techniques, I try to follow what's going on outside the .NET/Microsoft ecosystem. Clojure looks like a very interesting language. Erlang seems to solve some hard problems in an easy way. Storm seems to be way ahead of anything Microsoft can currently offer. Ruby developers have claimed high productivity for years. Git is a better source control system than anything Microsoft offers.

However, I feel constrained by my reliance on Visual Studio. I want to learn and use those other technologies as well as .NET, so I'm certainly not looking for tools that will further strengthen my bond with Visual Studio. Using plain vanilla Visual Studio is the least I can do to broaden my horizons.

Productivity boosts #

A common argument for a 'productivity tool' is that it makes you more productive. "Without #resharper my productivity drops by 50%, I'm amazed that you can manage without it". That's an interesting statement. How do you even measure productivity?

For the sake of argument, let's for a moment pretend that programmer productivity is measured by lines of code written. There's this myth going around that a professional programmer only writes 10 lines of code per day. This is probably not true, but even so, how many lines of code do you produce on average per day? 100? 200? Are you seriously going to claim that your productivity bottleneck is determined by how fast you can type? Really? Then learn to type faster.

Consider that most code is read a lot more than it's written. Code should be optimized for reading, not writing. Thus, productivity, if it can be measured at all, should be measured by how quickly programmers can read and understand a piece of code - not by how fast it can be written.

Furthermore, if you believe that Pair Programming is one good and productive way to produce software, you must also realize that at every given moment, at least one person isn't typing at all. As Martin Fowler puts it: "that [Pair-Programming halves the productivity of developers] would be true if the hardest part of programming was typing". In my experience, this is not the case. Thus, I'm not convinced that 'productivity tools' make anyone more productive.

If you've ever looked beyond the Microsoft echo chamber in the last decade, you will have heard a particular group of developers boast unmatched productivity. Those would be Ruby on Rails developers. Lately, it seems to me that many alpha geeks gravitate towards JavaScript (and particularly Node.js). And what about Python or Clojure? In all cases it seems that the reason why cutting edge programmers are leaving .NET, in favor of other languages and platforms, is because of better productivity. What do these languages have in common? Well, the preferred development environment certainly isn't Visual Studio. These programmers 'get by' with Vim, Emacs, Sublime Text, and many other editors. Apparently, it's possible to be 'crazy productive' without Visual Studio and a 'productivity tool'.

Railroading #

As Charles Petzold points out in his excellent article, Visual Studio enforces a certain bottom-up style of programming that isn't particularly aligned with business needs. Visual Studio (with or without 'productivity tools') makes it hard (but not impossible) to do Outside-In development.

My feeling is that whenever a tool helps us in a certain way, it closes a lot of other doors on us. We may not even be aware of what we aren't being shown, but if we can shake off the helping hand, we may also be able to see other options.

I don't mind being helped by a tool once in a while, but at other times, I'd rather make an informed decision by myself. At least I think it's important to realize that being helped means that decisions are being made for me. It's not a win-win situation. I may be able to finish a task quickly, but I lose the opportunity to learn. Not only that, but the more I rely on a tool for assistance, the more dependent do I become of it. The're a word for that. It's called Vendor lock-in.

Final thoughts #

All of this is highly subjective and personal. My personal style is to be very deliberate and patient. I go slowly in order to move fast.

In order to demonstrate just how slowly I go, I recorded half an hour of a TDD session. There's nothing special about this TDD session. I didn't pick it to impress anyone. I didn't pick the 'best' from a pool of a dozen candidates. I just recorded how I work and uploaded it. I dare you to watch it all the way through. It will be boring. You will see much think time and long periods of inactivity. This is actually a typical depiction of how I work. Yet, somehow, I still manage to produce software in such a quality that people keep coming back to me to pay me to do more.

If you watch just five minutes of that video, it should be clear to you that a 'productivity tool' wouldn't be of any help to me. It might not slow me down either, once I'd learned to use it, but it wouldn't make me more 'productive' either, so why should I bother with it?

This is just my opinion of 'productivity tools.' It's not a one-size-fits-all judgment. If you feel that you benefit from using your favorite 'productivity tool' I'm not going to tell you to change your ways. Likewise, don't judge me because I don't use a particular tool. Some programmers that I really respect use ReSharper. I respect them not because of, but rather despite of, that.

Comments

In case you missed the Tweet, the Google+ share or the announcement, my first course for Pluralsight, called Outside-In Test-Driven Development, is now available.

Comments

This article describes how object roles can be indicated by parts of a type name.

In my overview article on Role Hints I described how making object roles explicit can help making code more object-oriented. One way code can convey information about the role played by an object is to let a part of a class' name convey that information. This is often very useful when using Convention over Configuration.

While a class can have an elaborate and concise name, a part of that name can communicate a particular role. If the name is complex enough, it can hint at multiple roles.

Example: Selecting a shipping Strategy #

As an example, consider the shipping Strategy selection problem from a previous post. Does attribute-based metadata like this really add any value?

[HandlesShippingMethod(ShippingMethod.Express)]
public class ExpressShippingCostCalculator : IBasketCalculator

Notice how the term Express appears twice on two lines of code. You could successfully argue that the DRY principle is being violated here. This becomes even more apparent when considering the detached metadata example. Here's a static way to populate the map (in F# just because I can):

let map = Dictionary<ShippingMethod, IBasketCalculator>()
map.Add(ShippingMethod.Standard,
                       StandardShippingCostCalculator())
map.Add(ShippingMethod.Express,
                       ExpressShippingCostCalculator())
map.Add(ShippingMethod.PriceSaver,
                       PriceSaverShippingCostCalculator())

This code snippet uses some slightly unorthodox (but still valid) formatting to highlight the problem. Instead of a single statement per shipping method, you could just as well write an algorithm that populates this map based on the first part of each calculator's name. Follow that train of thought to its logical conclusion, and you don't even need the map:

public class ShippingCostCalculatorFactory : IShippingCostCalculatorFactory
{
    private readonly IEnumerable<IBasketCalculator> candidates;
 
    public ShippingCostCalculatorFactory(
        IEnumerable<IBasketCalculator> candidates)
    {
        this.candidates = candidates;
    }
 
    public IBasketCalculator GetCalculator(ShippingMethod shippingMethod)
    {
        return (from c in this.candidates
                let t = c.GetType()
                where t.Name.StartsWith(shippingMethod.ToString())
                select c).First();
    }
}

This implementation uses the start of the type name of each candidate as a Role Hint. The ExpressShippingCostCalculator already effectively indicates that it calculates shipping cost for the Express shipping method.

This is an example of Convention over Configuration. Follow a simple naming convention, and things just work. This isn't an irreversible decision. If, in the future, you discover that you need a more elaborate selection algorithm, you can always modify the ShippingCostCalculatorFactory class (or, if you wish to adhere to the Open/Closed Principle, add an alternative implementation of IShippingCostCalculatorFactory).

Example: ASP.NET MVC Controllers #

The default routing algorithm in ASP.NET MVC works this way. An incoming request to /basket/1234 is handled by a BasketController instance, /product/3457 by a ProductController instance, and so on.

The ASP.NET Web API works the same way, too.

Summary #

Using a part of a type name as a Role Hint is very common when using Convention over Configuration. Many developers react strongly against this approach because they feel that the loss of type safety and the use of Reflection makes this a bit 'too magical' for their tastes. However, even when using attributes, you can easily forget to add an attribute to a class, so in the end you must rely on testing to be sure that everything works. The type safety of attributes is often an illusion.

The great benefit of Convention over Configuration is that it significantly cuts down on the number of moving parts. It also 'forces' you (and your team) to write more consistent code, because the overall application is simply not going to work if you don't follow the conventions.

Comments

This article describes how object roles can be indicated by the use of Role Interfaces.

In my overview article on Role Hints I described how making object roles explicit can help making code more object-oriented. One way code can convey information about the role played by an object is by implementing one or more Role Interfaces. As the name implies, a Role Interface describes a role an object can play. Classes can implement more than one Role Interface.

Example: Selecting a shipping Strategy #

As an example, consider the shipping Strategy selection problem from the previous post. That example seemed to suffer from the Feature Envy smell because the attribute had to expose the handled shipping method as a property in order to enable the selection mechanism to pick the right Strategy.

Another alternative is to define a Role Interface for matching objects to shipping methods:

public interface IHandleShippingMethod
{
    bool CanHandle(ShippingMethod shippingMethod);
}

A shipping cost calculator can implement the IHandleShippingMethod interface to participate in the selection process:

public class ExpressShippingCostCalculator : 
    IBasketCalculator, IHandleShippingMethod
{
    public int CalculatePrice(ShoppingBasket basket)
    {
        /* Perform some complicated price calculation based on the
         * basket argument here. */
        return 1337;
    }
 
    public bool CanHandle(ShippingMethod shippingMethod)
    {
        return shippingMethod == ShippingMethod.Express;
    }
}

An ExpressShippingCostCalculator object can play one of two roles: It can calculate basket prices and it can handle basket calculations related to shipping methods. It doesn't have to expose as a property the shipping method it handles, which enables some more sophisticated scenarios like handling more than one shipping method, or handling a certain shipping method only if some other set of conditions are also met.

You can implement the selection algorithm like this:

public class ShippingCostCalculatorFactory : IShippingCostCalculatorFactory
{
    private readonly IEnumerable<IBasketCalculator> candidates;
 
    public ShippingCostCalculatorFactory(
        IEnumerable<IBasketCalculator> candidates)
    {
        this.candidates = candidates;
    }
 
    public IBasketCalculator GetCalculator(ShippingMethod shippingMethod)
    {
        return (from c in this.candidates
                let handles = c as IHandleShippingMethod
                where handles != null
                && handles.CanHandle(shippingMethod)
                select c).First();
    }
}

Notice that because the implementation of CanHandle can be more sophisticated and conditional on the context, more than one of the candidates may be able to handle a given shipping method. This means that the order of the candidates matters. Instead of selecting a Single item from the candidates, the implementation now selects the First. This provides a fall-through mechanism where a preferred, but specialized candidate is asked before less preferred, general-purpose candidates.

This particular definition of the IHandleShippingMethod interface suffers from the same tight coupling to the ShippingMethod enum as the previous example. One fix may be to define the shipping method as a string, but you could still successfully argue that even implementing an interface such as IHandleShippingMethod in a Domain Model object mixes architectural concerns. Detached metadata might still be a better option.

Summary #

As the name implies, a Role Interface can be used as a Role Hint. However, you must be wary of pulling in disconnected architectural concerns. Thus, while a class can implement several Role Interfaces, it should only implement interfaces defined in appropriate layers. (The word 'layer' here is used in a loose sense, but the same considerations apply for Ports and Adapters: don't mix Port types and Adapter types.)

Comments

This article describes how object roles can be indicated by metadata.

In my overview article on Role Hints I described how making object roles explicit can help making code more object-oriented. One way code can convey information about the role played by an object is by leveraging metadata. In .NET that would often take the form of attributes, but you can also maintain the metadata in a separate data structure, such as a dictionary.

Metadata can provide useful Role Hints when there are many potential objects to choose from.

Example: Selecting a shipping Strategy #

Consider a web shop. When you take your shopping basket to checkout you are presented with a choice of shipping methods, e.g. Standard, Express, and Price Saver. Since this is a web application, the user's choice must be communicated to the application code as some sort of primitive type. In this example, assume an enum:

public enum ShippingMethod
{
    Standard = 0,
    Express,
    PriceSaver
}

Calculating the shipping cost for a basket may be a complex operation that involves the total weight and size of the basket, as well as the distance it has to travel. If the web shop has geographically distributed warehouses, it may be cheaper to ship from a warehouse closer to the customer. However, if the closest warehouse doesn't have all items in stock, there may be a better way to optimize profit. Again, that calculation likely depends on the shipping method chosen by the customer. Thus, a common solution is to select a shipping cost calculation Strategy based on the user's selection. A simplified example may look like this:

public class BasketCostCalculator
{
    private readonly IShippingCostCalculatorFactory shippingFactory;
 
    public BasketCostCalculator(
        IShippingCostCalculatorFactory shippingCostCalculatorFactory)
    {
        this.shippingFactory = shippingCostCalculatorFactory;
    }
 
    public int CalculatePrice(
        ShoppingBasket basket,
        ShippingMethod shippingMethod)
    {
        var shippingCalculator =
            this.shippingFactory.GetCalculator(shippingMethod);
 
        return shippingCalculator.CalculatePrice(basket) + basket.Total;
    }
}

A naïve attempt at an implementation of the IShippingCostCalculatorFactory may involve a switch statement:

public IBasketCalculator GetCalculator(ShippingMethod shippingMethod)
{
    switch (shippingMethod)
    {
        case ShippingMethod.Express:
            return new ExpressShippingCostCalculator();
        case ShippingMethod.PriceSaver:
            return new PriceSaverShippingCostCalculator();
        case ShippingMethod.Standard:
        default:
            return new StandardShippingCostCalculator();
    }
}

Now, before you pull Refactoring at me and tell me to replace the enum with a polymorphic type, I must remind you that at the boundaries, applications aren't object-oriented. At some place, close to the application boundary, the application must translate an incoming primitive to a polymorphic type. That's the responsibility of something like the ShippingCostCalculatorFactory.

There are several problems with the above implementation of IShippingCostCalculatorFactory. In the simplified example code, all three implementations of IBasketCalculator have default constructors, but that's not likely to be the case. Recall that calculating shipping cost involves complicated business rules. Not only are those classes likely to need all sorts of configuration data to determine price per weight range, etc. but they might even need to perform lookups against external system - such as getting a qoute from an external carrier. In other words, the ExpressShippingCostCalculator, PriceSaverShippingCostCalculator, and StandardShippingCostCalculator are unlikely to have default constructors.

There are various ways to implement such an Abstract Factory, but none of them may fit perfectly. Another option is to associate metadata with each implementation. Using attributes for such purpose is the classic .NET solution:

public class HandlesShippingMethodAttribute : Attribute
{
    private readonly ShippingMethod shippingMethod;
 
    public HandlesShippingMethodAttribute(ShippingMethod shippingMethod)
    {
        this.shippingMethod = shippingMethod;
    }
 
    public ShippingMethod ShippingMethod
    {
        get { return this.shippingMethod; }
    }
}

You can now adorn each IBasketCalculator implementation with this attribute:

[HandlesShippingMethod(ShippingMethod.Express)]
public class ExpressShippingCostCalculator : IBasketCalculator
{
    public int CalculatePrice(ShoppingBasket basket)
    {
        /* Perform some complicated price calculation based on the
         * basket argument here. */
        return 1337;
    }
}

Obviously, the other IBasketCalculator implementations get a similar attribute, only with a different ShippingMethod value. This effectively provides a hint about the role of each IBasketCalculator implementation. Not only is the ExpressShippingCostCalculator a basket calculator; it specifically handles the Express shipping method.

You can now implement IShippingCostCalculatorFactory using these Role Hints:

public class ShippingCostCalculatorFactory : IShippingCostCalculatorFactory
{
    private readonly IEnumerable<IBasketCalculator> candidates;
 
    public ShippingCostCalculatorFactory(
        IEnumerable<IBasketCalculator> candidates)
    {
        this.candidates = candidates;
    }
 
    public IBasketCalculator GetCalculator(ShippingMethod shippingMethod)
    {
        return (from c in this.candidates
                let handledMethod = c
                    .GetType()
                    .GetCustomAttributes<HandlesShippingMethodAttribute>()
                    .SingleOrDefault()
                where handledMethod != null
                && handledMethod.ShippingMethod == shippingMethod
                select c).Single();
    }
}

This implementation is created with a sequence of IBasketCalculator candidates and then selects the matching candidate upon each GetCalculator method call. (Notice that I decided that candidates was a better Role Hint than e.g. calculators.) To find a match, the method looks through the candidates and examines each candidate's [HandlesShippingMethod] attribute.

You may think that this is horribly inefficient because it virtually guarantees that the majority of the injected candidates are never going to be used in this method call, but that's not a concern.

Example: detached metadata #

The use of attributes has been a long-standing design principle in .NET, but seems to me to offer a poor combination of tight coupling and Primitive Obsession. To be fair, it looks like even in the BCL, the more modern APIs are less based on attributes, and more based on other alternatives. In other posts in this series on Role Hints I'll describe other ways to match objects, but even when working with metadata there are other alternatives.

One alternative is to decouple the metadata from the type itself. There's no particular reason the metadata should be compiled into each type (and sometimes, if you don't own the type in question, you may not be able to do this). Instead, you can define the metadata in a simple map. Remember, 'metadata' simply means 'data about data'.

public class ShippingCostCalculatorFactory : IShippingCostCalculatorFactory
{
    private readonly IDictionary<ShippingMethod, IBasketCalculator> map;
 
    public ShippingCostCalculatorFactory(
        IDictionary<ShippingMethod, IBasketCalculator> map)
    {
        this.map = map;
    }
 
    public IBasketCalculator GetCalculator(ShippingMethod shippingMethod)
    {
        return this.map[shippingMethod];
    }
}

That's a much simpler implementation than before, and only requires that you supply the appropriately populated dictionary in the application's Composition Root.

Summary #

Metadata, such as attributes, can be used to indicate the role played by an object. This is particularly useful when you have to select among several candidates that all have the same type. However, while the Design Guidelines for Developing Class Libraries still seems to favor the use of attributes for metadata, this isn't the most modern approach. One of the problems is that it is likely to tightly couple the resulting code. In the above example, the ShippingMethod enum is a pure boundary concern. It may be defined in the UI layer (or module) of the application, while you might prefer the shipping cost calculators to be implemented in the Domain Model (since they contain complicated business logic). However, using the ShippingMethod enum in an attribute and placing that attribute on each implementation couples the Domain Model to the user interface.

One remedy for the problem of tight coupling is to express the selected shipping method as a more general type, such as a string or integer. Another is to use detached metadata, as in the second example.

Comments

This post announces the availability of the NSubstitute-based Auto-mocking extension for AutoFixture.

Almost two and a half years ago I added an Auto-mocking extension to AutoFixture, using Moq. Since then, a couple of other Auto-mocking extensions have been added, and this Sunday I accepted a pull request for Auto-mocking with NSubstitute, bringing the total number of Auto-mocking extensions for AutoFixture up to four:

• AutoFixture.AutoMoq
• AutoFixture.AutoRhinoMocks
• AutoFixture.AutoFakeItEasy
• AutoFixture.AutoNSubstitute

Kudos to Daniel Hilgarth for creating this extension, and for offering a pull request of high quality!

Comments

This article describes how object roles can by indicated by argument or variable names.

In my overview article on Role Hints I described how making object roles explicit can help making code more object-oriented. One way code can convey information about the role played by an object is by proper naming of variables and method arguments. In many ways, this is the converse view of a Type Name Role Hint.

To reiterate, the Design Guidelines for Developing Class Libraries provides this rule:

Consider using names based on a parameter's meaning rather than names based on the parameter's type.

As described in the post about Type Name Role Hints, this rule makes sense when the argument type is too generic to provide enough information about role played by an object.

Example: unit test variables #

Previously I've described how explicitly naming unit test variables after their roles clearly communicates to the Test Reader the purpose of each variable.

[Fact]
public void GetUserNameFromProperSimpleWebTokenReturnsCorrectResult()
{
    // Fixture setup
    var sut = new SimpleWebTokenUserNameProjection();
 
    var request = new HttpRequestMessage();
    request.Headers.Authorization = 
        new AuthenticationHeaderValue(
            "Bearer",
            new SimpleWebToken(new Claim("userName", "foo")).ToString());
    // Exercise system
    var actual = sut.GetUserName(request);
    // Verify outcome
    Assert.Equal("foo", actual);
    // Teardown
}

Currently I prefer these well-known variable names in unit tests:

• sut
• expected
• actual

Further variables can be named on a case-by-case basis, like the request variable in the above example.

Example: Selecting next Wizard Page #

Consider a Wizard in a rich client, implemented using the MVVM pattern. A Wizard can be modeled as a 'Graph of Responsibility'. A simple example may look like this:

This is a rather primitive Wizard where the start page asks you whether you want to proceed in a 'default' or 'custom' way:

If you select Default and press Next, the Wizard will immediately proceed to the Progress step. If you select Custom, the Wizard will first show you the Custom step, where you can tweak your experience. Subsequently, when you press Next, the Progess step is shown.

Imagine that each Wizard page must implement the IWizardPage interface:

public interface IWizardPage : INotifyPropertyChanged
{
    IWizardPage Next { get; }
 
    IWizardPage Previous { get; }
}

The Start page's View Model must wait for the user's selection and then serve the correct Next page. Using the DIP, the StartWizardPageViewModel doesn't need to know about the concrete 'custom' and 'progress' steps:

private readonly IWizardPage customPage;
private readonly IWizardPage progressPage;
private bool isCustomChecked;
 
public StartWizardPageViewModel(
    IWizardPage progressPage,
    IWizardPage customPage)
{
    this.progressPage = progressPage;
    this.customPage = customPage;
}
 
public IWizardPage Next
{
    get 
    {
        if (this.isCustomChecked)
            return this.customPage;
 
        return this.progressPage;
    }
}

Notice that the StartWizardPageViewModel depends on two different IWizardPage objects. In such a case, the interface name is insufficient to communicate the role of each dependency. Instead, the argument names progressPage and customPage are used to convey the role of each object. The role of the customPage is more specific than just being a Wizard page - it's the 'custom' page.

Example: Message Router #

While you may not be building Wizard-based user interfaces with MVVM, I chose the previous example because the problem domain (that of modeling a Wizard UI) is something most of us can relate to. Another set of examples is much more general-purpose in nature, but may feel more abstract.

Due to the multicore problem, asynchronous messaging architectures are becoming increasingly common - just consider the growing popularity of CQRS. In a Pipes and Filters architecture, Message Routers are central. Many variations of Message Routers presented in Enterprise Integration Patterns provide examples in C# where the alternative outbound channels are identified with Role Hints such as outQueue1, outQueue2, etc. See e.g. pages 83, 233, 246, etc. Due to copyright reasons, I'm not going to repeat them here, but here's a generic Message Router that does much the same:

public class ConditionalRouter<T>
{
    private readonly IMessageSpecification<T> specification;
    private readonly IChannel<T> firstChannel;
    private readonly IChannel<T> secondChannel;
 
    public ConditionalRouter(
        IMessageSpecification<T> specification,
        IChannel<T> firstChannel,
        IChannel<T> secondChannel)
    {
        this.specification = specification;
        this.firstChannel = firstChannel;
        this.secondChannel = secondChannel;
    }
 
    public void Handle(T message)
    {
        if (this.specification.IsSatisfiedBy(message))
            this.firstChannel.Send(message);
        else
            this.secondChannel.Send(message);
    }
}

Once again, notice how the ConditionalRouter selects between the two roles of firstChannel and secondChannel based on the outcome of the Specification. The constructor argument names carry (slightly) more information about the role of each channel than the interface name.

Summary #

Parameter or variable names can be used to convey information about the role played by an object. This is especially helpful when the type of the object is very general (such as string, DateTime, int, etc.), but can also be used to select among alternative objects of the same type even when the type is specific enough to adhere to the Single Responsibility and Interface Segregation principles.

This article describes how object roles can by indicated by type names.

In my overview article on Role Hints I described how making object roles explicit can help making code more object-oriented. When first hearing about the concept of object roles, a typical reaction is: How is that different from the class name? Doesn't the class name communicate the purpose of the class?

Sometimes it does, so this is a fair question. However, there are certainly other situations where this isn't the case at all.

Consider many primitive types: do the names int (or Int32), bool (or Boolean), Guid, DateTime, Version, string, etc. communicate anything about the roles played by instances?

In most cases, such type names provide poor hints about the roles played by the instances. Most developers already implicitly know this, and the Design Guidelines for Developing Class Libraries also provides this rule:

Consider using names based on a parameter's meaning rather than names based on the parameter's type.

Most of us can probably agree that code like this would be hard to use correctly:

public static bool TryCreate(Uri u1, Uri u2, out Uri u3)

Which values should you use for u1? Which value for u2?

Fortunately, the actual signature follows the Design Guidelines:

public static bool TryCreate(Uri baseUri, Uri relativeUri, out Uri result)

This is much better because the argument names communicate the roles the various Uri parameters play relative to each other. With the object roles provided by descriptive parameter names, the method signature is often all the documentation required to understand the proper intended use of the method.

The Design Guidelines' rules sound almost universal. Are there cases when the name of a type is more informative than the argument or variable name?

Example: Uri.IsBaseOf #

To stay with the Uri class for a little while longer, consider the IsBaseOf method:

public bool IsBaseOf(Uri uri)

This method accepts any Uri instance as input parameter. The uri argument doesn't play any other role than being an Uri instance, so there's no reason that an API designer should go out of his or her way to come up with some artificial 'role' name for the parameter. In this example, the name of the type is sufficient information about the role played by the instance - or you could say that in this context the class itself and the role it plays conflates into the same name.

Example: MVC instances #

If you've ever worked with ASP.NET MVC or ASP.NET Web API you may have noticed that rarely do you refer to Model, View or Controller instances with variables. Often, you just return a new model directly from the relevant Action Method:

public ViewResult Get()
{
    var now = DateTime.Now;
    var currentMonth = new Month(now.Year, now.Month);
    return this.View(this.reader.Query(currentMonth));
}

In this example, notice how the model is implicitly created with a call to the reader's Query method. (However, you get a hint about the intermediary variables' roles from their names.) If we ever assign a model instance to a local variable before returning it with a call to the View method, we often tend to simply name that variable model.

Furthermore, in ASP.NET MVC, do you ever create instances of Controllers or Views (except in unit tests)? Instances of Controllers and Views are created by the framework. Basically, the role each Controller and View plays is embodied in their class names - HomeController, BookingController, BasketController, BookingViewModel, etc.

Example: Command Handler #

Consider a 'standard' CQRS implementation with a single Command Handler for each Command message type in the system. The Command Handler interface might be defined like this:

public interface ICommandHandler<T>
{
    void Execute(T command);
}

At this point, the type argument T could be literally any type, so the argument name command conveys the role of the object better than the type. However, once you look at a concrete implementation, the method signature materializes into something like this:

public void Execute(RequestReservationCommand command)

In the concrete case, the type name (RequestReservationCommand) carries more information about the role than the argument name (command).

Example: Dependency Injection #

With basic Dependency Injection, a common Role Hint is the type itself.

public BasketController(
    IBasketService basketService,
    CurrencyProvider currencyProvider)
{
    if (basketService == null)
        throw new ArgumentNullException("basketService");
    if (currencyProvider == null)
        throw new ArgumentNullException("currencyProvider");
 
    this.basketService = basketService;
    this.currencyProvider = currencyProvider;
}

From the point of view of the BasketController, the type names of the IBasketService interface and the CurrencyProvider abstract base class carry all required information about the role played by these dependencies. You can tell this because the argument names simply echo the type names. In the complete system, there could conceivably be more than one implementation of IBasketService, but in the context of the BasketController, some IBasketService instance is all that is required.

Summary #

The more generic a type is, the less information about role does the type name itself carry. Primitives and Value Objects such as integers, strings, Guids, Uris, etc. can be used in so many ways that you should strongly consider proper naming of arguments and variables to convey information about the role played by an object. This is what the Framework Design Guidelines suggest. However, as types become increasingly specific, their names carry more information about their roles. For very specific classes, the class name itself may carry all appropriate information about the object's intended role. As a rule of thumb, expect such classes to also adhere to the Single Responsibility Principle.