Sep 30

Introduction to messaging primitives

One of the most flexible design/architecture techniques is event-driven/message-oriented design. It offers unparalleled ability to loosely couple, accomplish Dependency Inversion, facilitates composability, etc. Message-oriented systems are by nature asynchronous. This means that a message is sent and the process that sent the message continues on to do other processing without knowing whether the message was received by the other end. Think of it like sending an email. You send an email, close your email client, and go on to do something else. Later, you may return to your email program and notice that the email you sent bounced. But, you had to return to your email program to see that because you where asynchronously doing something else.

I’ve been working on an OSS project for a while that provides a framework for simple (once you wrap your head around the degree of loose coupling and asynchronousness) and flexible message-oriented design. This framework is based on a small set of types that I call primitives. Before going into what you can do with the framework, this post will first cover the primitives.

If you’re used to message-oriented systems, some of this may be very understandable. For those new to message-orientation, you’ll understand why I started with the primitives.

The message primitives source code is on GitHub and can be added to your Visual Studio project/solution from NuGet (but you may want to wait to add this package to your project/solution until a future post, as it’s a dependency of the framework, so you don’t need to add this package manually (i.e. it’s referenced and NuGet will automatically get it for you).

The primitives are based on the most simple messaging building blocks (or patterns, which are well-defined in the book Enterprise Integration Patterns but can also be seen on and consist of a generic Message, a generic message Consumer, a generic message Producer, a generic Pipe, a generic Command message (a specialized Message), a generic Event message (a specialized Message), and a Bus.

The Message pattern is modeled in the Primitives via the IMessage interface, detailed as follows:

    public interface IMessage
        string CorrelationId { get; set; }

The idea is that the message you want to send/receive implements this interface and you add the properties you need to contain the data. The interface contains a property CorrelationId to provide a first-class ability to correlate multiple messages together involved in a particular interaction, transaction, or saga. But, for the most part, you should use either Command or Event instead.
As mentioned above, you don’t normally implement IMessage directly, you derive from one of two types of IMessage-derived interfaces. The first interface I’ll talk about is the ICommand interface. This is a marker interface to add compile-time checked semantics that I’ll detail in a future post, and detailed as follows:

    public interface ICommand : IMessage

The marker interface pattern is a pattern that allows associating metadata with a type. In this case the metadata is the ability to differentiate at compile-time that a particular type is a Command.
The Command message pattern allows you to encapsulate all the information required to request a handler perform a command, or otherwise change state. The type of command to be performed is the type of the ICommand-implementating class. Message handlers should typically have no run-time state, so everything the command handler needs to perform the command should be included within the ICommand type. For example, if I want to make a request to a handler to create a client, I may have a CorrectClientAddressCommand with the following detail:

  public class CorrectClientAddressCommand : ICommand
    public string CorrelationId { get; set; }
    public string ClientId { get; set; }
    public Address PriorAddress { get; set; }
    public Address Address { get; set; }

As with marker interfaces, we have the ability to introduce metadata when we’re defining our messages. Just like something can be known as a Command because it implements ICommand, we can introduce more depth of intent in our messages. For example, if a client moves, their address changes, but using a command like CorrectClientAddress does not include that intent. We could create a new, identical command named “MoveClientCommand” that is effectively identical to CorrectClientAddressCommand in content (or even derive from the same base class). And that way we can include semantic intent with the message. Why would you want to do that? In the address change example, when a client corrects their address they may never have received important mailings. In the case of a correction, the organization can re-send important mailings. In the MoveClientCommand you may not want to re-send all that information (waste of money, annoys clients, etc.) and instead send a card welcoming them to their new home and taking advantage of an opportunity to impress the clients.
The second message type pattern is an Event. And just like an event we deal with in day-to-day life: it’s a moment in time and information about that moment in time. From the standpoint of messages, we say that an event is moment of time in the past, otherwise known as a fact. It’s important to remember that it’s a past fact and really should be considered as immutable data. Typically events model the details about a change in state. We model events in Primitives with the IEvent interface, with the following details:

    public interface IEvent : IMessage
        DateTime OccurredDateTime { get; set; }

Notice that we force implementation of IMessage (that is, include CorrelationId) and add an OccurredDateTime property.
When we want to communicate an event, we call sending an event “publishing” the event. This concept is considered “pub/sub” (or publish/subscribe) where something that publishes an event never knows how many subscribers (or if any) are subscribed to receive an event. When utilizing event-driven in this way, we’re very loosely coupled and any number of things can subscribe to these events and extend without affecting the sender (i.e. code changes or availability).
Typically, when we talk about what we model with events, or facts about the past, we model state changes and include information about that state change. To correlate to the CorrectClientAddressCommand; upon a successful address change, the handler of that message may publish a ClientAddressCorrectedEvent. Which may look like this:

  public class ClientAddressCorrectedEvent : IEvent
    public string CorrelationId { get; set; }
    public DateTime OccurredDateTime { get; set; }
    public string ClientId { get; set; }
    public Address PriorAddress { get; set; }
    public Address Address { get; set; }

Circling back to the CorrelationId concept, the event includes the CorrelationId field. If the event is published due to the processing of another message then we would copy that CorrelationId value into the event. That way, when something receives the event (remember that messaging is asynchronous) it can correlate it back to another message, likely one that it sent.
Now that we have a grasp on some basic message types and concepts, lets talk about how we use those messages.
The thing that performs consumption or handling of a message is a Consumer. It is modeled in the Primitives via the IConsumer interface, detailed as follows:

    public interface IConsumer<in T> where T:IMessage
        void Handle(T message);

Notice that it’s a generic interface and the generic type must implement IMessage. The implementer of IConsumer<in T> must also implement a Handle method that takes in the an instance of the message that the class would process. So, if I wanted to create a class to implement a handler for the CorrectClientAddressCommand command, it may look like this:

  public class CorrectClientAddressCommandHandler: IConsumer<CorrectClientAddressCommand>
    public void Handle(CorrectClientAddressCommand message)
      // ...

Now, since we’re using interfaces, a class can implement more than one handler. For example, if I also wanted to process the ClientAddressCorrectedEvent, I may update my class to be something like:

  public class CorrectClientAddressCommandHandler : IConsumer<CorrectClientAddressCommand>, IConsumer<ClientAddressChangedEvent>
    public void Handle(CorrectClientAddressCommand message)
      // ...
    public void Handle(ClientAddressChangedEvent message)
      // ...

But, as you can tell from the type of the handler class (CorrectClientAddressCommandHandler) that it’s named very specifically to be a CorrectClientAddressCommand handler. I typically use that convention and have one handler per class, which offers a greater flexibility in terms of loosely coupled and composability. But, in the end, it’s up to you what convention you’d like to use.
To write code to handle a particular message you simply implement IConsumer<int T> for one or more types of messages
The thing that performs production of a message is called a Producer, and is model in Primitives as IProducer<out T>, detailed as follows:

    public interface IProducer<out T> where T:IMessage
        void AttachConsumer(IConsumer<T> consumer);

Similar to IConsumer<in T>, except for the fact the generic type is covariant instead of contravariant, the generic type must implement IMessage.
Now this is where the loose coupling and composability takes us into an advanced realm. You’ll notice that the IProducer has a single method AttachConsumer that accepts an IConsumer<in T> where T is the same generic type as the producer. This is probably very different from a typical imperative design that might have a method that returns a message. We don’t do it in an imperative way because 1) we have message consumption abstraction (IConsumer) and 2) the fundamental asynchronousness of messaging. The production and consumption of messages does not occur in a consistent, sequential fashion such that we would know where to place a call to a method that returns a message. Instead, we tell the producer who can consume the message and whenever the producer gets around the producing that message, it passes it right along to the consumer.
We may have a class that is a producer of CorrectClientAddressCommand and could define it as follows:

  CorrectClientAddressController : IProducer<CorrectClientAddressCommand>
    private IConsumer<CorrectClientAddressCommand> consumer;

    public void AttachConsumer(IConsumer<CorrectClientAddressCommand> consumer)
      this.consumer = consumer;

    public void CorrectClientAddress(Client client, Address newAddress)
      if(consumer == null)
        throw new InvalidOperationException(
          "@nameof(consumer) was null during invocation of CorrectClientAddress");

      var command = new CorrectClientAddressCommand()
        CorrelationId = Guid.NewGuid().ToString("N");
        ClientId = client.Id;
        PriorAddress = client.Address;
        Address = newAddress;

Notice an application-/domain-specific method CorrectClientAddress that contains all the information required to send a CorrectClientAddressCommand (and the CorrectClientAddressCommand handler would perform the heavy lifting asynchronously and potentially in another thread/process/node, if you’re looking for scalability).
You could use this class like this:

  var controller = new CorrectClientAddressController();
  controller.AttachConsumer(new CorrectClientAddressCommandHandler());

And then when the CorrectClientAddress method is called, the consumer is invoked.
The last Primitive type is the Pipe. The pipe is a general abstraction to model anything that is both a consumer and producer. And, in fact, is just an interface that implements IConsumer and IProducer, detailed as follows:

    public interface IPipe<in TIn, out TOut>
      : IConsumer<TIn>, IProducer<TOut>
        where TIn : IMessage where TOut : IMessage

With IPipe the consumer has a different generic type name than the producer, but, a single type could be used for both (IPipe<MyMessage, MyMessage>) to model a true pipe.
Typically though, we use IPipe to model various other messaging patterns like Filters (something that would ignore a message based on content) or Translators (something that converts one message type into another message type).
The next message pattern is the Bus. A bus is modeled with the IBus type. This bus model is basically facilitates implementing a Control Bus. The Control Bus facilitates connecting message producers with message consumers in a more loosely coupled way.
Remember the CorrectClientAddressController IProducer example? The code was tightly coupled to both CorrectClientAddressController and CorrectClientAddressCommandHandler and we had to new-up both in order to hook them up. If I’m writing code that produces a message like CorrectClientAddressCommand, I don’t want it to be directly coupled to one particular handler. After all, we’re looking for loosely coupled and asynchronous. With tight coupling like that I might as well just do all the work in the CorrectClientAddress method and skip all the messaging.
A bus allows us to build up something at runtime that does that connection. It will keep track of a variety handlers and invoke the correct handler when it consumes a message.
As you probably guessed, the IBus is a consumer and thus implements IConsumer<in T>. But, a bus can handle a variety of different messages, so it uses IMessage for its type parameter, as detailed:

    public interface IBus : IConsumer<IMessage>
        void AddTranslator<TIn, TOut>(IPipe<TIn, TOut> pipe)where TIn : IMessage where TOut : IMessage;
        void AddHandler<TIn>(IConsumer<TIn> consumer) where TIn : IMessage;
        void RemoveHandler<TMessage>(IConsumer<TMessage> consumer) where TMessage : IMessage;

As we can see from the definition of IBus is also allows the connection of pipes or translators.
So, if I wanted the type CorrectClientAddressCommandHandler to handle a CorrectClientAddressCommand (and produce a ClientAddressCorrectedEvent and a ClientAddressCorrectedEventHandler type to handle a ClientAddressCorrectedEvent message, could use a mythical bus implementation Bus like this:

  var bus = new Bus();
  bus.AddHandler(new CorrectClientAddressCommandHandler());
  bus.AddHandler(new ClientAddressCorrectedEventHandler());

I could then send the command to the bus and have the command handler handle the message and the event handler handle event, without ever specifically attaching one handler to the producer. Sending that command could be done as follows:

  bus.Send(new CorrectClientAddressCommand());

“So?”, you may be thinking. Remember when I spoke about how events are subscribed to, and how there may be more than one subscriber to an event? I have a command handler than can only attach to one consumer, how would I be able to do that? That’s one of the benefits of the Bus, it deals with that for you. If I added another event handler, I may create my bus as follows:

  var bus = new Bus();
  bus.AddHandler(new CorrectClientAddressCommandHandler());
  bus.AddHandler(new ClientAddressCorrectedEventHandler());
  bus.AddHandler(new ClientAddressCorrectedEventHandler2());

The Bus would then handle forwarding the event to both of the event handlers, avoiding the need to write a different IConsumer implementation that would manually do that (e.g. a Tee).
These are examples of composing in-memory buses. That is, they process messages within the same process (and in a specific order).

There’s a couple of important concepts that relate to messaging. Immutability and Idempotency.
I’ve already touched on immutability. But, it’s important to remember that due to the asychronous nature of messaging that you should consider the messages you send to be immutable. That is, you should’t change them. For example, I could write some error-prone code like this:

  var command = new CorrectClientAddressCommand();
  command.ClientId = 0;

In the case of a message that is physically sent to a queue (covered in a future post) that message has been serialized to the queue and has left this process. Making a change to the command object cannot be seen by the consumer of that message. If we’re talking about an in-memory bus, it could be the same situation, but the time Send returns the message has already been processed. If any of the message handlers are multi-threaded then the command object may or may not be already handled by the time Send returns. In any case, it’s best to view sent messages as immutable to avoid these race conditions.
Another concept that often comes up in messaging is Idempotency. Idempotency is the quality of a message consumer to produce the same side-effects with the same parameters, no matter how many times it is invoked.
What I’ve detailed so far with in-memory buses is effectively Reliable Messaging. If IBus.Send returns, the message was reliably processed. When we start to include message queues and accept messages over the wire, running on multiple computers, we have to deal with the possibility that another server or process might fail and might have to re-send a message. This typically only happens when the reliability settings of the Queue are not set to the highest level (for example “at-least-once delivery”, where we trade performance for the potential that a message may be sent more once. In situations like this you may want to send a message that allows the consumer be an Idempotent Receiver.
In our CorrectClientAddressCommand we’ve effectively facilitated a Idempotent Receiver, no matter how many times I send a CorrectClientAddressCommand the resulting client address will be the same. Other types of messages make it difficult to have an Idempotent Receiver. For example, if I had an IncreaseClientAgeCommand, processing it would always increase an Age property of a client. If at-least-once-delivery was configured for the queue, this could occasionally lead to incorrect ages. You may want to either have a command like SetClientAgeCommand or better yet (avoid pedantry) and have a CorrectClientBirthDateCommand.

And with that, we have a good introduction of messaging and an intro to the messaging primitives library. In a future post I’ll detail the implementation of these primitives: the patterns library.

Mar 10

Writing Unit Tests is Hard, Because…

hard-work There are lots of things in life that are hard.  There is also lots of things in life that we make hard for ourselves when we don’t have to.  Unit testing is one of those things that we’ve made hard for ourselves and we don’t have do.

Accidental Complexity

Before I go into not making unit testing harder than it needs to be, let me first talk about accidental complexity.  Fred Brooks details two types of complexity in his book No Silver Bullet – Essence and Accidents of Software Engineering: Essential Complexity and Accidental Complexity.  Essential complexity is complexity inherent in the problem.  Accidental complexity is the complexity engineers add in an effort to solve a problem.  Essential complexity cannot be avoided, accidental complexity can.

So, how does this apply to unit testing?  Well, when unit testing is hard it is an indication that there is unnecessary coupling.  If you can’t test a controller without the model that accesses the database (and thus an RDMS, an instance of the database, test data, etc.) then you have accidental complexity that hinders your ability to test.  There are ways to design software and structure code such that a controller can be composed at run-time and interact with abstractions so that the uniqueness of the controller (or the value-add) can be tested independently.  Because we *can* design this way, anything that hinders fine-grained testing is accidental complexity, by definition.

Dealing with this accidental complexity with unit tests is straightforward, but requires thinking about design.  Changing a design to remove the accidental complexity is doable, but not adding the accidental complexity at all is preferable.  TDD helps a lot with that; but that’s for another post—the focus of this post will be about changing design, or removing accidental complexity.

Removing accidental complexity is really about decoupling.  Two of the most useful techniques for creating a decoupled design are the Dependency Injection pattern and the Dependency Inversion Principle.

Dependency Inversion Principle

The Dependency Inversion Principle (DIP) states:



This is extremely important for designing and implementing testable software.  Let’s be clear here; we’re talking about unit tests (or automated tests) where we want to be able to (at least) have fine-grained tests that test the smallest unit possible per test which allows us to find and fix problems much more quickly.  With top-down designed software, there’s no easy way to separate out these smaller units of code for testing.

Let’s look an example.  Say I have an MVC application that has a CategoryController.  And with any typical MVC application the controller translates view actions into interactions with the model.  In a top-down design, you might have a CategoryController constructor like this

public class CategoryController
	private CategoryModel model;
	public CategoryController()
		model = new CategoryModel();

66795Imagine if this top-down design continued, where CategoryModel depended on various things, and the various things that CategoryModel depended on depended on various other things…  CategoryController would be the tip of an iceberg with untold depths of dependencies below the surface, all of which limiting our ability to use CategoryController in any but one scenario (especially not the testing scenario).

From a functionality standpoint top-down design works. But to test the tip of the iceberg we end up testing the whole iceberg.  To test CategoryController we’d have to write a test like this.

public void ListActionReturnsListOfCategories()
	var controller = new CategoryController();
	var result = (ViewResult) controller.List();
	Assert.IsTrue(result.ViewData.Model is IEnumerable<Category>);
	IEnumerable<Category> listCategories = (IEnumerable<Category>) result.ViewData.Model;
	Assert.AreEqual(1, listCategories.Count());

But, for this to work we have to make sure all the requirements are met for CategoryModel to operate correctly.  If CategoryModel is an abstraction around a Repository implementation or a data context (like Entity Framework), then there is a lot of configuration required for our simple tests to run.  Having test setup code to do this configuration is simply not feasible.  It’s unreasonable for test setup code to install and configure SQL Server, for example.  Even if we did spend the time to get that configuration done (and that would be on one developer workstation) we’d end up testing the controller, the model, the database server, the database scheme, the test data, etc.—any of which could cause a test failure limiting our ability to focus on where the failure was (or whether it was a configuration error).   No, we want to be able to execute tests with zero configuration dependencies.

In this top-down design implementation, the controller takes a dependency on CategoryModel (has ownership).  We want to invert that dependency such that ownership is inverted and that the controller simply takes a dependence at the code level on an abstraction.  But, since the controller is currently the owner of the model, we must first talk about The Dependency Injection Pattern.

Dependency Injection Pattern

The Dependency Injection pattern defines that the dependencies that one unit (class or method) requires be injected into the unit.  This means that the dependency be instantiated outside the unit and be passed in (either in a constructor if it is a mandatory class dependency, a property if it is an optional class dependency, or as a parameter of the method if it is a method dependency).  Optional class dependencies and method dependencies are really indications that there is a responsibility problem (i.e. something has taken on too much responsibility) so I generally try to focus solely on constructor injection.

In the case of our CategoryController, this means creating a model abstraction and injecting an instance of an implementation of that abstraction into our controller.  Our model is fairly simple, so our abstraction might look like this:

public interface ICategoryModel
	IEnumerable<Category> List();

And we’d derive our CategoryModel class from ICategoryModel:

public class CategoryModel : ICategoryModel
	public IEnumerable<Category> List()

And in order to use this in production code, instead of simply instantiating the controller, we’d instantiate the model first:

var controller = new CategoryController(new CategoryModel());

And, of course, modify CategoryController like this:

public class CategoryController
	private ICategoryModel model;
	public CategoryController(ICategoryModel categoryModel)
		model = categoryModel;

Keep in mind that the composition of the controller would be done in a MVC-compatible factory.

But, now we are free to use any ICategoryModel implementation when composing a CategoryController.  In the case were we want to focus on the unit of CategoryController.List(), we can mock away the production-level model and focus solely on the CategoryControl.List() unit. So, we might update our test method as follows:

public void ListActionReturnsListOfCategories()
	var controller = new CategoryController(new MockCategoryModel());
	var result = (ActionResult) controller.List();
	Assert.IsTrue(result.ViewData.Model is IEnumerable<Category>);
	IEnumerable<Category> listCategories = (IEnumerable<Category>) result.ViewData.Model;
	Assert.AreEqual(1, listCategories.Count());

Bottom-up Design and Composability

Ice-Cubes Now we are able to reason about smaller parts of our system.  This allows us (or forces us, depending on your point of view) to compose our systems from smaller, decoupled, parts (like ice cubes instead of one iceberg).  We instantiate several objects independently (each of which is injected into another) to compose a system.  We can compose those instances in the way we’d need for our production system, or we could compose those instances in a way that allows is to test individual units of code. This allows us to get away from the tip of the iceberg design smell that plagued our ability to test.

By taking on this bottom-up design design philosophy it allows us the freedom to compose our systems and subsystems in code (in other words at run-time) offering great flexibility in the granularity at which we can test.  We can still perform integration and system-level automated testing, but now we’re free to have fine grain tests that will run quickly and fail fast allowing very quick and tight dev/test cycles.

Test-Driven Design

If you’re new to this bottom-up design philosophy and want to get better at composable systems, I’d recommend trying to do Test-Driven Design (TDD) whenever you can.  TDD forces you to create simple tests before you start to write the system under test, so it forces you to have a testable (and thus likely composable) design.


When we allow accidental complexity into our software, design, and processes; what we are really doing is adding needless coupling.  The more complex something is, the more it is coupled to many, potentially unrelated, things.  With that increased coupling it’s hard to make fine-grained changes to things.  To make the changes we want to make takes much more work and causes much more instability.  But that’s for yet another blog post.

Feb 22

The Dreaded Re-write

There are lots of people who have arbitrarily said “never do a rewrite”.  Some have caveats like “unless you have to” (without criteria).  Some have even called it the “single worst strategic mistake” a software team can make.  Refactoring is great, but sometimes a product is in dire straits and the existing behaviour is part of the problem and ignoring any problem in software is a huge mistake.

Software evolves over time, the initial design and architecture is based on what was known when the project started.  If a software product lasts long enough, changes to, and additions to, functionality eventually mean the design and architecture are no longer sufficient.  We have all sorts of great patterns and practices that allow us to create design and architectures that are able to accommodate changing requirements, but future-proofing software is worse than a total rewrite (i.e. designing something that is not based on actual requirements—designing on what might be). “Never do a rewrite” is a sign of a immature project team not capable of re-architecting to something better.

When software lives beyond the applicability of its design and architecture, software effectively goes on life-support.  Working with software not designed to accommodate certain features means adding these features involves a lot of tweaking and hacking (keeping in mind, “fixing” something might entail adding features). Adding features becomes complex and error-prone.  Adding features becomes harder and harder over time and the development team becomes less and less responsive.  The amount of time tweaking and hacking required to support new features is directly proportional to the amount of time required to fix the bugs that are introduced by those tweaks and hacks. That’s the nature of a tweak/hack.  There will be times when it’s all-hands-on-deck trying to fix newly introduced problems–and no real forward progress can be made on new features or otherwise.

Experienced software designers and architects ignore this “never re-write” distortion and instead recognize when a design/architecture is no long sufficient.  It is then that they take action. But, rather than misleading absolutes like “never do a re-write” or superlatives like “single worst strategic mistake” (because all absolutes and superlatives have exceptions in software development: “never say never”), they begin a re-architecture whose end-goal is effectively a “re-write”. This doesn’t mean hide a re-write by calling it re-architecture; let’s look a some criteria to temper a re-architecture.

Writing software isn’t an atomic operation; things happen while you’re architecting/designing/writing and by the time something is complete the assumptions you had going in may be wrong.  This is the fundamental premise of agile software teams: the ability to recognize that change and be able to accommodate for it.  Re-design and re-architecture is the same way, you can’t simply take a team of people and “go dark” and expect to come out at the end and be successful.

Redesigning and re-architecting needs to take into account the environment it is in, the environment that needs redesign, the environment that is effectively funding the redesign.  Re-architecture needs to take into account that writing any code takes time (even if it’s writing new code) and accept existing products will exist until a re-architecture is fully complete and will need attention during that time.

Re-architecture should not be considered a “total re-write” it should be viewed as an “eventual re-write”. “total re-writes” are viewed as atomic—something that cannot be interrupted between the start and the completion.  Re-architecture is a phased re-write.   A sly architect will re-architect a system so that parts of the system may be redesigned and implemented independently of one another.  There are many ways to approach this independence, all of which deal with abstraction.  Even the simplest of maintainable software has abstractions.

A well componentized architecture facilitates the phased nature of re-architecture.  But, we’re talking about something with a sub-optimal architecture, aren’t we?  So, which abstractions do we use?  In a simple inter-process architecture, such as:


…we have typical object seams where the typical OO data-hiding comes into play and we can vary our implementation details as we see fit—one component at a time.  As I mentioned in my previous post, the concept of seams allows us to define a logical API grouping as a seam.  In much the same way object-orientated languages provide abstraction boundaries (well defined) we can define logical abstraction boundaries (in the form of logical API groupings) to create new seams by which we can organize and plan re-architecture.  In our previous architecture, we can see a couple of logic abstractions that we can view as seams:

Deploy process seams

As we can see, we’ve recognized seams at the inter-process boundaries of the Server and the Service.  This allows is to not only organize independent work bounded by component seams, but also allows us to organize independent work bounded by inter-process seams.  If we maintain these seams over time, we can view the Server and the Service processes as implementation details that are free to evolve how they need to.  These are fairly easy abstraction points, and probably ones that seem (no pun intended) obvious. You probably already work within constrictions like this.

With a sufficiently complex code, breaking work up on at these inter-process seams may still be a huge amount of work to bite off.  In order to delineate work to a more manageable level, a re-architecture might take some interrelated classes and logically group them together to create a new component whose existing interaction with the rest of the current system is now defined as a seam.  For example:

inter-component seams

This new “component” could be logical or it could be physical.  The main point here is we are bounding work to a specific API subset that we can delineate as a seam.  We can communicate and reason about this  seam in the same way as any other abstraction. We define that seam API as immutable and therefore decouple the work (implementation detail) from the rest of the system down to the build/link level.  Changes to anything in this seam will require a re-build but will not require and code changes outside of the seam.

This seam abstraction allows us to limit the side-effects of a change and better estimate the work involved.  This allows to delineate work and assign tasks, as well as better gauge progress once started.  The key to agile development is to better gauge and demonstrate progress—without that, the effort appears to “go dark” and success is doomed.

What logical abstractions you define and use seams is up to our project, the people on it, the requirements, and the timeframes involved.  You should optimize use of seams to your team—don’t assume you ca cleave off any subset of APIs and be successful.

Once all the implementation details behind a dependent seam are complete (implemented, tested, etc.) then the seams can be evolved (hopefully just a refactoring, but could be deeper).  Obviously both logical sides of a seam should be re-architected before attempting to evolve the API defined by the seam—otherwise we break the decoupling we created when work started on the one side.

Typical abstraction patterns (adapters, model-view, facades, etc.) can facilitate decoupling the implementation detail of the re-design of one side of the seam from the now well-defined API.  It may seem like architecture overkill, but when you come back later (and sometimes that’s much later) to refactor the seam API if you focus your work within abstractions, you’ll be much more efficient and sane.


Re-architecting portions of software is a very powerful way of decoupling parts of a system from others so that work can be undertaken independently.  Using the concept of seams allows you to better define and delineate parts of a system whose architecture is insufficient and allows to improve it more efficiently and effectively, without an overwhelming amount of work.

Feb 17

Seam expansion

No, this isn’t a post about gaining weight: busting at the seams.  It’s about expanding on the concept of “seams”.

My first introduction to “seams” was with Michael Feathers’ book Working Effectively with Legacy Code. In which he defined a seam as:

A seam is a place where you can alter behaviour in your program without editing that place.

He also detailed some types of seams: Preprocessing Seams, Object Seams, and Link Seams. As well as detailing Enabling Point, or the thing that represents the choice of which behaviour to enable at that seam.

Feathers described seams and their use in the context of testing.  I think the concept of seams can be used for other places we want to reason about code, design, or architecture.  Before I get into that, let’s have a quick overview of the types of seams that Feathers detailed.

Preprocessing Seams

This seam is fairly straightforward. It’s a point where a compiler’s preprocessor lets you enable or disable behaviour based on preprocessor directives (.NET, C++, etc) or preprocessor logic (C++, etc.).  I’m sure we’re all familiar with using #if DEBUG to enable/disable behaviour.

Object Seams

This seam is also straight-forward, it basically details the abstraction behind OOD and that through polymorphism and an object’s published API (or behaviour) we can facilitate enabling or disabling behaviour at compile-time.

Link Seams

The final seam (although, the second in Working Effectively With Legacy Code) basically details all the other possibilities (at least in the context of object-oriented languages) in that they are seams not related to the compiler.  I think this type of seam offers a wonderful ability to facilitate abstraction at so many other levels and allows us to reason about code, design, and architecture in very powerful way.  The rest of this post will be about expanding this seam concept (link-level or link-time) into other areas to allow us to reason about software design more powerfully.

Seams as an artefact of design

One place where we can get immediate value from seams is to view them as an independent attribute of a design or architecture.  We could view seams as just a side effect of integrating components in a system, but by viewing them as independent artefacts we can reason better about software and its design and architecture. Much like a directed graph that has nodes and edges, a dependency diagram details components and dependencies or relationships.  In most cases, we can view these dependencies and relationships as seams that we can reason about over-and-above testing, regardless of how they are dependant.

Seams are effectively recognizing APIs (or subsets of APIS) and allowing them to be independent of the elements on either side of the seam.  When we do that, either side of the dependency is really dependant on the seam, not on the other side.  If we take that point of view, we can then modify one side to modify the behaviour of the other without directly modifying that other side.  We’re really just thinking about abstraction in a different way.

The link seam that Feathers details encompasses link-time resolutions (in terms of .NET: references) but also includes dynamic resolution (run-time linking done either by the runtime, or by the application code—e.g. Double Dispatch, the dynamic keyword, etc.). Feathers’ Link Seam is effectively a run-time resolution seam but can be expanded to allow reasoning about much more of a system’s design.  For example, in many contemporary systems we use web APIs to communicate between components.  This really isn’t the “link” operation that which Feathers details; but equally as useful when viewed as a seam.  A web API is a much more understandable API front-end to implementation—we can view all APIs this way when we use seams.  We can even view a logical grouping of components in a design and their API as a seam.  There may be no unique physical separation between a logical group and the things that depend on it, but again, equally as useful to view its seams.

Some readers may be thinking, these are just views. While this is a very good analogy and it shows you’re grasping the concept, seams are not views.  Views are different in that the view is an implementation detail behind a physically componentized API, the seam is an outward representation of a grouping of APIs (physically componentized or logically grouped).  Any particular component with an API may, of course, implement that API with a view behind it; but that’s orthogonal to seams. e.g. a seam exists whether or not the View pattern is used.

Once we can reason about seams we can then reason about the rest of the design around those seems.  As I’ve mentioned, we can view a logical grouping of APIs as a logical component that publishes a specific API.  If we maintain that specific API over time, we can change the implementation behind that API without having to modify that rest of system that depends on it.  We, of course, will likely have to re-compile or re-build and re-deploy; but if we have maintained that seam, that re-compile our re-build will not fail.

Recognizing, defining, and reasoning about seams at these levels provides a lot of flexibility in software design and architecture.  This post serves as an introduction to this expanded seam concept that will be shown in my next post.

Sep 08

“CONSIDER providing method Close(), in addition to the Dispose(), if close is standard terminology in the area” considered deprecated

In Framework Design Guidelines there is a guideline “CONSIDER providing method Close(), in addition to the Dispose(), if close is standard terminology in the area”.  Recently this guideline has been considered deprecated.  Teams at Microsoft have come to the conclusion that this is more confusing than helpful.

The guideline basically suggests that another method be added to disposable types where something like “Close” may make more sense for the particular interface and implement IDisposable explicitly.  For example:

This would mean that Dispose() can be called when using the `using` statement, but could not be used without first casting to IDisposable if you wanted to call Dispose directly (and thus make you prefer `Close`) as show on line 12 of the above example.  Now you can avoid doing the explicit implementation of IDisposable and not add a class-specific method that just calls through to Dispose.  For example:

When the Guidelines where first written .NET was in its infancy.  Dispose has become very ubiquitous in .NET and something that you figure out very early when developing in .NET.  I surmise that because IDisposable is used across the Framework to such a degree that anything that acts like Dispose but isn’t named Dispose is not intuitive to programmers.

There should be a forthcoming blog post from the teams that better detail the impetus of the decision (i.e. the confusions) and the documentation at should eventually be updated to reflect the change.

As you can see in the current reference source (, that Socket.Dispose is no longer implement explicitly.  Of course, Close still exists because removing that would be a breaking change.  New classes will not implement Dispose explicitly and will not have extraneous methods like `Close`.  But, `Close` is still very common and will never entirely be gone from the Framework.

Aug 12

Maslow’s Hammer

When you go about any task, knowledge and experience from a vast range of specialties can benefit you in your approach to a task.  I often draw similarities in writing software to building houses, for example—mostly as a an allegory. Writing software is a task largely performed by humans, as such human nature comes into play.  Research and understanding about human nature can benefit people who write or are involved in the writing of software.  Abraham Maslow had a goal of better understanding the human mind.  In that journey, he recognized the law of the instrument and created a hammer allegory.  This concept seems to often apply to software technologists and I find myself having to refer to it way too often.  I’d thought I’d detail it here and put a bit of my spin on it.

The Golden Hammer

Maslow detailed in his book The Psychology of Science, the concept of if all you have is a hammer, everything looks like a nail.  This is sometimes referred to The Golden Hammer, and a specialization of the law of the instrument.  Basically, what Maslow recognized was that we go about performing a task, we have only our knowledge and experience to apply to performing that task.

Maslow opined that if your knowledge is so narrow such that the only tool you know how to use is a hammer, that—when given a task to perform—you’ll project nails into places where nails don’t really exist and thus want to use a hammer to complete the task.  The corollary to this is, of course, that as soon as you learn how to use a hammer you’re hell-bent on using it, no matter the consequences.

I’m too often reminded of this in software development, that software developers like to take what is effectively an empirical process and make it a defined process whenever possible.  They want take their new-found (“shiny new thing”), or tried-and-true, knowledge and create a “just apply x” process to it.  I try to point this out when I can, and offer ways to help break free of that, or at least question the status quo, here on my blog and elsewhere.

“Full stack developers”

Lately I’ve recognized that the same thing is happening at a broader level.  Developers have coined the term “full stack developer”—which is a developer that has knowledge and/or experience with every tool/library/framework from the lowest level to the highest level.  For some, this may be 3-layer development: WinForms front-end, .NET business logic layer, SQL Server data layer/back-end and all the devops dependencies that go with that. For others this may be HTML front end, MVC framework-dujour, web service layer, database—with one flavour per devops platform for each.  Etc. Software does get written this way, I cannot deny that—we all know that software gets written and used despite things like technical debt, this, etc.  But, “full stack” is really just another incarnation of Maslow’s Hammer.  We’re conditioned that software developers know one of a handful of defined processes (use stack X, or use stack Y) and know the process of applying that process in different places.  I’m coining the term “Society of the Stack” to describe this—where there seems to be an actual community around using and promoting the use of a “stack” of pre-defined components/procedures to rubber-stamp where ever possible.  This simply strikes me as a resurgence of SDLC (and away from agile) at an architectural level.

If you want to break free of this type of thinking, try to put thought into how you design software or how your current design is used.  If you consider yourself a “full stack developer”, periodically check that every component or process in that stack makes sense in the situation you’re using it in. (if it’s not, you’ve recognized a technical debt).  To be able to do that effectively, always be knowledgeable about any alternatives to any components or processes within that stack.  Writing software is a science, the use of any component or process in a given situation should be backed up by facts—don’t go down the dogma rat hole.

All software developers are recovering process addicts, we need to band together to make sure we don’t let that monkey cloud our judgement.


Yes, I know that Maslow’s Hammer is a tired analogy to how software developers write software; but software developers keep focusing only the knowledge they have to solve problems and seem to fail to widen their horizons to the fact that there are better, proven, solutions to the problems at hand.  If they only looked/listened.  The only thing I feel I can do—in addition to pointing out alternative solutions—is to reiterate Maslow’s Hammer in the hopes that it helps at least one person break free of the Society of the Stack.

Aug 05

If you think you need to use an ORM, think some more.

Software developers took great strides when they defined and/or embraced Agile.  Agile tells use that software is about the user, it’s not about all the supporting process.  You should be talking to your user, find out what they need and give them that—they don’t need process, they don’t need huge design documents, and they don’t need only things you want to work with.

But, developers continue to want to force process where it’s not needed or doesn’t add value.  Developers tend to learn something and want to “processize” it—make it rote.  Especially with things that may excite them.  They continually want to reduce the amount of thought they put into things.

ORMs are a perfect example.  “Back in the day”, when SQL databases were either the only thing available for storing data or were middleware decreed by the ivory tower (data) architect or IT department, writing object-oriented software was at odds with relational data.  An object could be structured data and a relational database (when following the penultimate normal form) was a subset of linked, flat tables.  Objects with their structured data and behaviour, of course, could not be accurately represented by a subset of over-normalized flat (but linked) tables.  Enter impedance mismatch.  And ORMs where created to abstract the impedance mismatch (and other things) away from the object-oriented design so that software design could be done how it needed to be and be separate from the design of the data.

Bottom-up design

One of the problems with many systems that use ORMs is that they were designed from the bottom up.  The design started with implementation details like data, data structure, and thus implementation details like database type; before what the software needed to do was known.  ORMs helped with the impedance mismatch of the relational data mapped to objects, but forced developers down the relational database make-work machine.  ORM and mapping is an explosion of work and complexity that is only worth it if it is necessary.  It’s an explosion of work partially because despite an ORM, the “object” it maps to still has impedance mismatches and is an object at the data layer and still needs to be mapped to “view” types.

Much of the time it seems that a Visual Studio project is created and a bunch of nuget packages are added before discussion with the user/stakeholders to ask “what do you need”.  Much of the implementation details have already been decided upon before any real understanding of the problem that needs to be solved has begun.  Sometimes it’s even worse; developers have their go-to architecture and they rubber-stamp it into all the situations they’re involved in.

Design by rote

Mindlessly repeating something without thought is the definition of rote.  I see design-by-rote too often due to people using only the things they have experience with (and thus are confortable with) and have not tried to learn more about the problem at hand and learn more about alternatives that would help solve that problem better.

Rote is mindless, which means not enough thought has been put into the architecture or the most important part of the design.

Clearly software can be written like this, because this is a prevalent problem in the software industry.  It can be done but it introduces a lot of work, process, and usually frustration for the end users because the software development effort focuses on process, ceremony, and implementation details.  Sometimes, instead of focusing on the solution the end user needs.


I really don’t think you can know about alternatives to the point where you can know where to apply them without understanding the specifics and nuances of some basic theories and concepts.  ACID, of course, is something you really have to grok in order to decide a relational database is a good fit or not.  Relational databases have strong consistency-during-write guarantees that drastically affect availability.  You, of course, can’t really grok how availability relates to consistency and thus how and where your prioritization of availability can impact your choice of database type without understanding the CAP theorem.  Without understanding CAP, you’ll assume you can have consistency, availability, and be able to support partitions all at the same time.

Without understanding CAP, you won’t understand you can only have two. And, of course, if you’ve already forced yourself to pick a relational database before knowing more about what the user needs, you won’t know how to prioritize consistency, availability, and partition support.  Without knowing this prioritization you won’t know if you should pick a CA database, an AP database, or a CP database.

Relational databases almost always lie in the CA space—which means their support for a partition is almost nil.  If you need to support multiple nodes and have one or more of those nodes not being connected to all the others for even a small amount of time, relational is a poor choice.  (yes, it can be done, but the work/hardware/system involved is not cost effective for most scenarios.  Plus at the cost of availability).  Imagine if Google had that level of consistency such that any write of data locked out any other read of that data until it completed—consider they have thousands upon thousands of nodes.  Imagine blocking thousands of nodes and still having a responsive (available) site.

If CP or AP is the area you think you need to be in, then you might want to consider a document database, a key-value database (or store), or maybe even a column-oriented or tabular database.  Most of the “web scale” databases lie in the AP area, like Dynamo (key-value), Cassandra (column-oriented/tabular), CoucheDB, and Riak (both document-oriented).  You can still go with the CP side of things and have you choice of the same types of nosql databases like MongoDB (document-oriented), HBase (Hadoop: column-oriented), or Redis (key-value)

There are all sorts of great tools out there that specialize in solving all sorts of specific problems is some of the best ways possible.  Shoe-horning one thing to solve all problems is rarely the best solution.  Data analysis for example; SQL databases (and thus the need for ORM) that contain operational data may not be the best solution for any given system’s data analysis and reporting needs.  In fact, that’s what normalization is: an attempt to make the data as flexible as possible for reporting.  Data normalization isn’t about making the software run faster, it’s about making querying the data more flexible (remember the ‘Q’ in “SQL”?).  In fact, relational databases make writing data fairly slow (and thus means locking out reads for potentially longer than they need to—potentially slowing the software).  So, a write-heavy system that didn’t need ACID-like consistency might be slow or not scale well (or at all).  If the number of reads are drastically more (i.e. you’re talking about factors more) than writes, a relational database may be a bad choice.

So, in addition to understanding ACID, CAP, CA databases, AP databases, CP databases, key-value stores, relational databases, column-oriented databases, document databases, etc. you also have to understand where reporting fits in and how you need to fulfil reporting requirements.  Without knowing what tool is best for your end users, you won’t know how to architect your system.  There are all sorts of great business intelligence (BI) tools to help with data analysis of generally-transactional data.  BI tools are great for allowing end-users to do ad-hoc reporting (rather than software developers spending weeks/months creating one-off reports for the end-users). To support those may require a specific architecture.  A data-warehouse, for example, might be a good thing for most BI tools.  That data-warehouse might be best suited as sourcing from a periodically updated relational database.  At which point, having your operational data on a relational database may be a complete waste of time—introducing ORMs, ORM configuration, mapping, etc. solely for supporting the choice of relational databases.  i.e. you don’t need an ORM if you use a document database.

Arguably, effort into creating and writing ORMs might have better been served by writing more useful databases (i.e. getting nosql databases sooner) or pressuring the people involved away from process and toward software tools and middleware that made sense.  But, that’s where things went.  And on the .NET side of things, that was really just perpetuated by the re-writes of lots of existing Java tools (like Hibernate).

ORMs are like any other tool—they have a specific time and place.  If you find you’ve got to put screws into wood, don’t pick a hammer to do it.  Hammers are great for the task they’re design for (just like ORMs), but other tools are better designed for certain tasks.

Jul 23

Long Paths and .NET

If you’ve been following me on Twitter the last little while you might have noticed a few tweets bemoaning long paths in .NET code.  This hasn’t been something new to me, but I decided to attempt to do something about it in the last little while.

Supporting files and directories with a long path is fairly easy with Windows. Unfortunately, other aspects of Windows haven’t supported long paths in their entirely. The file system (NTFS), for example, supports long paths quite well; but other things like Command Prompt and Explorer don’t. This makes it hard to entirely support long paths in any application, let alone in .NET.x

What is “long path”?

Some of you (and I envy you) probably don’t know what a “long path” is.  It’s different from “long names”—which is a filename long than the archaic 8.3 filenames and support spaces.  Windows, for the longest time (and still does, for that matter) supported paths (drive specifier, directory, subdirectories, filename, extension) *up to* about 260 chars.  There are multiple ways to get around that (which actually create long paths and lead you down a path of anguish) but to support paths larger that 260 chars you have to use the long path support in Windows (and NTFS).  This support (which is essentially Unicode paths) supports up to 32,000 characters in a path.  (don’t talk to me if you reach **that** limit).  This still has its limits in that a *directory* is still limited to 256 characters (which is really a feature of the driver for that file system—but NTFS, last time I checked, supports up to to 256 characters per directory (which stems from 260: 256 chars for a directory, 3 chars for the drive specifier and one char for the null).  But, 256 chars for a directory name ought to be enough for everyone :).

Supporting a Long Path in .NET

This has been a bit tricky in .NET. Several attempts like (a more up to date version has made its way into .NET in classes like LongPath LongPathFile and LongPathDirectory. But, these libraries do not seem to support the entire original API (Path, File, Directory) and not all file-related APSs (including FileInfo, DirectoryInfo, FileSystemInfo).

Often times long path support is an after thought. Usually after you’ve released something and someone logs bug (e.g. “When I use a path like c:users300 chars removedDocument.docx your software gives me an error”. You can likely support long paths with the above-mentioned libraries, but you end up having to scrub your existing code that works with regular paths and re-design it to suit these new APIs (causing full re-tests, potential new errors, potential regressions, etc.).

So, I’m announcing an open-source library that I’ve created: LongPath (or Pri.LongPath on nuget).

LongPath is a .NET 4.5 library that attempts to make dealing with long paths *much* easier.  LongPath originally started as a fork of LongPaths on Codeplex; but after initial usage it was clear that much more work was involved to better support long paths. So, I drastically expanded the API scope to include FileInfo, DirectoryInfo, FileSystemInfo to get 100% API coverage supporting long paths. (with one caveat: Directory.SetCurrentDirectory, Windows does not support long paths for a current directory).

LongPaths allows your code to support long paths by providing a drop-in replacement for the following System.IO types: FileInfo, DirectoryInfo, FileSystemInfo, FileInfo, DirectoryInfo, FileSystemInfo. You simply reference the Pri.LongPath types you need and you don’t need to change your code.

Obviously to replace only 6 types in a namespaces (System.IO) and not the rest is problematic because you’re going to need to use some of those other types (FileNotFoundException, FileMode, etc.)–which means referencing System.IO and re-introducing the original 6 types back into your scope. I feft that not having to modify your code was the greater of the two evils. Resolving this conflict is easily solved through aliases.  So, if you’re used to one of the System.IO classes FileInfo, DirectoryInfo, FileSystemInfo, FileInfo, DirectoryInfo, FileSystemInfo, you simply add the following aliases to your C# file and go on about your business.

I think there’s currently 300 test that exercise the library pretty well; but if you find any issues, let me know via an issue on github, or a push request with a failing test.  Or, fix it and send me a push request with the fix and a new passing test.

I’m going to add support for prior versions of .NET (and future then they’re available) in the next little while (and over time); but if you’re interested in contributing, see the issues list on github, or add a new issue, or fork and start making changes.


Jul 17

Iterator Methods

Despite being around a while, I find that Iterator Methods haven’t gotten nearly as much attention they deserve and aren’t as understood maybe as they should be.  So, I thought I devote a post to Iterator Methods.

MSDN documents an Iterator Method is a method that performs a custom iteration over a collection and also uses the yield keyword.  I don’t think given C#’s evolution since yield was introduced that such a narrow definition is necessary.  I’d expand that definition to detail a method that returns a deferred enumerable.

A typical example of an iterator method:

This is a simple iterator method with a compile-time sequence of numbers that we want to be able to iterate.  While you might think this is the same as the following:

…it’s much more powerful than that.  Returning a collection instance requires that the entire collection be allocated in memory and that each element actually exist when the iterator method is called.  The second part is one of the most interesting things that iterator methods offer, deferred execution.  You can get that sort of thing with LINQ, but you can write your own deferred execution without having to hand-write a complex IEnumerable<T> implementation.  (I say “hand-write” because the compiler writes one for you).

For example, I wrote long ago about using an iterator method to return an IEnumerable to iterate all future key presses.  Something like this:

This creates an infinite IEnumerable<char> that effectively contains data from the future.  Something you couldn’t possibly do with a collection type instance.

This is a fairly pedantic example, but it shows the power of what you can do with iterator methods.

MSDN describes these types of methods as performing a custom iterator over a collection; here’s an example:

Now, pay attention to the possibility here and not the fact that LINQ to Objects could do the same thing.  But, again, why limit “Iterator Methods” to something that uses yield return.  I would still consider this an Iterator Method:

If the incoming IEnumerable was deferred, so too would this method.

Iterator methods allow you to operate at the element level rather than at the sequence level.  They allow you to process a sequence without having to know about, or even have in-memory, the entire sequence.  This offers a composability that Bill Wagner describes in much more detail in More Effective C# (Item 17). Suffice it to say, it allows you to decouple processing a sequence from the storage model used to store that sequence (or the fact that no storage model for the “sequence” may exist).  This offers huge gains in the ability to process large quantities of data more-or-less independently from the amount of memory we have at our disposal.

In a future post I hope to get into a specific case of where iterator methods can provide easy ways of dealing with sequences that would otherwise be limited by memory.

Jul 05

Testing framework assumptions

Back in the day (before there were unit testing tools), when I wanted to prototype (i.e. test my assumptions) how I would use a framework for certain things, I would perform some experimental development with the creation of a test application.  This would sometimes be a WinForms app, or sometimes a console app; but the type really doesn’t matter.  What matters was that how I was going to use a given framework (.NET Framework for example) was prototyped and validated before I got to far into certain parts of development.

One problem with doing that was that the application was largely throw-away and while that gave me the knowledge that could be used within the production application, it was lost on any other team members.  And in some cases they may be performing the same work in isolation.

Unit Testing Tools

Enter unit testing tools.  At a philosophical level unit testing tools are just for unit tests.  A unit test tests the smallest testable unit of code (typically a method) that given outputs or side-effects occur with given inputs.  But, we can think of them more broadly than that.  Unit testing tools are effective ways of performing any automated testing and we can expand out use of these tools to do much more than just unit testing.

Nowadays all my prototyping is typically done in a unit testing tool.  I can simply churn out a new test method to prototype almost any bit of code.  It allows me to invoke that code whenever I want either manually or automatically.  I can evolve that code from under test to in production by refactoring to other classes, etc.

Some may say this is a form of TDD, but it’s more than that.  I can create blocks of code that I want to prototype without any assertions just to get a basic understanding of code that I will need in production.  Once I’m done prototyping, I can either add assertions or refactor the code into production classes then evolve the test method or create new ones.  Or, I can simply leave the test method alone as a means of documenting the prototype and it can live with the code in source code control.

For example, I may need to use MessageQueue in a specific way.  I can create a test method to prototype that usage and verify it through compilation and execution:

Of course, with the ability to constantly verify assertions, this type of prototype code can explicitly detail *why* the code does what it does; but, sometimes it’s just a convenient place to keep sample code related to a project.  In cases like this, I may add a category to the test method so that I can wire it off from automated test runs.  For example, if I just want sample code on how to use a particular API in a framework, I may add an “Infrastructure” category:

One of the first things I do when I create a new solution in Visual Studio is to add a test project and I live in there most of the time prototyping and experimenting quickly and easily.  I encourage you to make use of your unit testing tools for as many things as possible.