I really think it’s time I assemble my scattered code goodies into a more maintainable and correctly unit-tested assembly. For every new private fun-project I start, I always find myself spending too much time settings things up and pick this from there and that from here and copy and paste and booom! … but no more of that now.

Let’s do it incrementally to make it easier to follow as a reader.

Since I call this first part Contracts, I guess an explanation could come in handy. I like to be explicit when coding C#. I also like the book Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries by Krzysztof Cwalina and Brad Abrams. There’s an online correspondence at MSDN: Design Guidelines for Developing Class Libraries. Go read it if you haven’t yet. One of things I do to be explicit is to never let garbage enter my code. I therefore always check the parameters of a public method before executing any logic:

public void Foo(Bar bar)
{
    if (bar == null)
    {
        throw new ArgumentNullException("bar");
    }
    ...
}

That way I can guarantee that any logic executed after the check will work as advertised when given proper parameters, i.e., I don’t need to check parameters in private or protected methods.

I also strive for designs with as much immutability as possible. This means that when an object has been constructed, its invariants or internal state will not change at any time. Doing this makes sharing problems in threading scenarios so much easier to deal with. It will usually also reduce the publically visible parts of a type, which means that the complexity is reduced. Furthermore, since the behavior of a type will be unchanged ofter construction, unit-testing the type will be easier, since the number of possible codepaths are reduced.

I check constructor parameters the same way as I check method parameters:

class Artist
{
    private readonly Palette palette;

    public Artist(Palette palette)
    {
        if (palette == null)
        {
            throw new ArgumentNullException("palette");
        }

        this.palette = palette;
    }
    ...
}

By checking all dependencies at the time of construction, I can guarantee that all public methods of the type will work as advertised when given proper parameters, i.e., I don’t need to check the state of the type itself before calling them. A properly constructed object means that it’s usable. Period.

Now, doing these checks can be a bit verbose and tedious. Wrapping them in some kind of helper class would ease the typing-burden. It could also increase the readability, if done properly in a semantic context. It can also open up the possibility of adding more goodies inside the wrapped check, like file logging of errors, etc.

Microsoft has provided one kind of solution to this: Code Contracts. But that is something I cannot use, since I do much of my coding for Windows CE/Mobile devices with .NET Compact Framework, which is unsupported for the Code Contracts. Also, I find it to be a bit too heavy (it has many, many features that I neither want to use or can implement myself). I like lightweight. This is what I’d like to do:

public void Foo(Bar bar)
{
    Precondition.IsNotNull(bar, "bar");
    ...
}

Which would just wrap the previous logic. By throwing in the complementary IsNull, it would read:

public sealed class Precondition
{
    public static void IsNotNull(object o, string name)
    {
        if (o == null)
        {
            throw new ArgumentNullException(name, "Precondition check failed. " +
                                                  "Object (" + name + ") is null; " +
                                                  "expected non-null.");
        }
    }

    public static void IsNull(object o, string name)
    {
        if (o != null)
        {
            throw new ArgumentNullException(name, "Precondition check failed. " +
                                                  "Object (" + name + ") is non-null; " +
                                                  "expected null.");
        }
    }
}

The NUnit tests for the precondition checker would be:

[TestFixture]
sealed class PreconditionTest
{
    [Test]
    public void null_doesnt_throw_for_isnull_but_non_null_does()
    {
        var nullo = default(object);
        var nonnullo = new object();

        Assert.DoesNotThrow(() => Precondition.IsNull(nullo, "nullo"));
        Assert.Throws(() => Precondition.IsNull(nonnullo, "nullo"));
    }

    [Test]
    public void non_null_doesnt_throw_for_isnotnull_but_null_does()
    {
        var nonnullo = new object();
        var nullo = default(object);

        Assert.DoesNotThrow(() => Precondition.IsNotNull(nonnullo, "nullo"));
        Assert.Throws(() => Precondition.IsNotNull(nullo, "nullo"));
    }
}

In the same vein as I check the preconditions of a constructor or regular public method, I check the advertised postconditions. That way I can guarantee that if a caller provides input that satisfies the preconditions, then the method will either succeed (postcondition fulfilled) or fail (postcondition breached). Nothing else. A failure is not that false is returned instead of true for a boolean property. Instead, for that same property, a failure would be if neither true or false can be returned, because the underlying driver that checks some hardware state cannot do its job properly. Or something similar. For instance, a device facade could have this method:

public void SuspendDeviceAtSlot(int index)
{
    Precondition.IsInRange(index, 0, this.devices.Count - 1);
    var device = this.devices[index];
    device.Suspend();
    Postcondition.IsFalse(device.Active());
}

The postcondition checker more or less just mirrors the precondition checker, but instead of throwing ArgumentException or ArgumentNullException, an InvalidOperationException is thrown:

public sealed class Postcondition
{
    public static void IsNull(object o, string name)
    {
        if (o != null)
        {
            throw new InvalidOperationException("Postcondition check failed. " +
                                                "Object (" + name + ") is non-null; " +
                                                "expected null.");
        }
    }

    public static void IsNotNull(object o, string name)
    {
        if (o == null)
        {
            throw new InvalidOperationException("Postcondition check failed. " +
                                                "Object (" + name + ") is null; " +
                                                "expected non-null.");
        }
    }
}

The NUnit tests for the postcondition checker would be:

[TestFixture]
sealed class PostconditionTest
{
    [Test]
    public void null_doesnt_throw_for_isnull_but_non_null_does()
    {
        var nullo = default(object);
        var nonnullo = new object();

        Assert.DoesNotThrow(() => Postcondition.IsNull(nullo, "nullo"));
        Assert.Throws(() => Postcondition.IsNull(nonnullo, "nullo"));
    }

    [Test]
    public void non_null_doesnt_throw_for_isnotnull_but_null_does()
    {
        var nonnullo = new object();
        var nullo = default(object);

        Assert.DoesNotThrow(() => Postcondition.IsNotNull(nonnullo, "nullo"));
        Assert.Throws(() => Postcondition.IsNotNull(nullo, "nullo"));
    }
}

All of this, including NUnit dependencies, can be fetched from the Mercurial repository at https://joger.googlecode.com or cloned with hg clone https://joger.googlecode.com/hg/ joger.