Type Name Role Hints by Mark Seemann
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.
