If you want people to use your extension methods…

If you want people to use your extension methods…

… you need to make them discoverable. That means temporarily abandoning your solution-structure-based namespaces and placing them directly in the namespace of the class you are extending so it comes up in intellisense immediately. Even if it’s from a totally different library, or System.* itself.

namespace YourCompany.Common.Extensions {    // don't expect anyone to find this here    public static class LinqExtensions { ... }}namespace System.Linq // can't miss it!{    public static class LinqExtensions { ... }}

If you’re using ReSharper you can also hit Alt+Enter and add the following so it won’t trigger code inspection warnings:

// ReSharper disable CheckNamespacenamespace System.Linq// ReSharper restore CheckNamespace{    public static class LinqExtensions { ... }}

Label your services!

Here’s a code snippet showing a little habit of mine — something I do to all my domain and application services:

public interface IPortfolioRepository : IDomainService{    ...}public interface IPortfolioAdministrationService : IApplicationService{    ...}

What’s in these base interfaces? Nothing. They are just labels, used to help make make object roles explicit:

public interface IApplicationService {}public interface IDomainService {}

Why is this a good idea?

  1. It helps makes implicit concepts — e.g. this is a domain service — explicit.
  2. It grants you freedom with your class names, without having to suffix everything with Service or Event.
  3. It lets you do cool stuff like write integration tests to check all your application services are registered correctly.

They’re not only limited to services, by the way. Use them for aggregate roots, entities, value types, and other types of objects:

public interface IPortfolio : IAggregateRoot{    ...}public interface IPortfolio : IEntity{    ...}public class Money : IValueType{    ...}public class BookAddedToPortfolio : IDomainEvent{    ...}

Udi Dahan’s Making Roles Explicit is a must-see presentation on this subject, if you haven’t already seen it. In fact, this example is only a small subset of what you can do with this technique.

Back to basics: What is state?

If you’re a new developer, one term you’ll hear used a lot is state. I remember I struggled with the idea at first, so I thought I’d write a brief introduction to the concept of state, and how it is applied to a few design and testing principles.

What is state?

Let’s use me as an example. Here are three facts that describe my current state:

  • My name is Richard.
  • I’m 23 years old.
  • I just ate some of my flatmate’s pancakes for lunch (wohoo!).
  • I’m in a pretty good mood.

In code, you might represent this as:

public class Person{    public string Name;    public int Age;    public Activity CurrentActivity;    public bool IsHungry;    public MoodType Mood;}

These fields comprise my state. Some are unlikely to change (my name, for instance) while others are much more volatile (I will be hungry again in a few hours).

So you can see state changes over time. For example, my state right now is totally different than my state after 40 hours of nonstop travel from London from New Zealand — I arrived tired, and pretty frazzled. Both these states are different again than when I’m asleep.

State can be recorded, persisted (e.g. saved to a Person table in a RDBMS) and tracked over time. Usually, though, we’re only interested in the current state.

So state is just data, right?

Well… yes and no. When persisted, state becomes data, and in an object, state represents the data portion. Remember object-oriented programming combines behaviour (methods) with data (state).

But at a higher level, state represents the overall picture of an object right now, how it will behave, and what range of actions are available. A good example of this is the State Pattern from the GoF book. In their example, a TCP network connection has different states: established, closed, or listening for an incoming connection. These states are each encapsulated into an object, assigned to a field and the TCPConnection delegates behaviour to the current state:

So you can see in examples like this, state is more than just data — it affects behaviour too.

Unit testing state vs unit testing behaviour

This is something you might hear in the context of TDD and BDD. In short, testing on state means looking at an object’s visible state after something happened, and checking that all the values are correct.

bankingService.Transfer(chequeAccount, savingsAccount, 100.0);// State-based assertionsAssert.AreEqual(0.0, cheque.Balance);Assert.AreEqual(100.0, savings.Balance);

In comparison, testing on behaviour means using mocks to verify the expected methods are called.

bankingService.Transfer(chequeAccount, savingsAccount, 100.0);// Behaviour-based assertionschequeAccount.AssertWasCalled(account => account.Withdraw(100.0));savingsAccount.AssertWasCalled(account => account.Deposit(100.0));

Generally behaviour-based testing is preferred, because:

  1. Focusing on behavioural seams (methods on interfaces) results in looser coupling, because the internal implementation of objects should change more often than the interfaces between them.
  2. The internal state of an object is private, and you shouldn’t be looking at it anyway — the basis of the Tell Don’t Ask principle.

Stateless services

An object’s state effects its behaviour. For example, when I eat, I feel full. If I eat too much, I feel sick — I can’t continue eating over and over.

Services, on the other hand, should be stateless. Imagine a dice-based random number generator. Every dice roll is a clean start — it should not retain any memory between rolls. To simplify usage and scale better, all service calls should be like this.

Another simpler example of unwanted state is services with methods like Initialize(), Start(), Connect(), Open() etc that must be called before other methods. Users of this service need to take responsibility for calling it and thus managing the lifecycle of the service — an unreasonable burden that introduces unnecessary coupling.

Explicit state transitions

One newer technique in domain-driven design is recognizing important state transitions, and making them explicit through the use of events. A simple example of this could be when your bank account balance goes below zero, its state becomes overdrawn:

public class Account{    public void Withdraw(Decimal amount)    {        balance -= amount;        if (balance < 0)            DomainEvents.Raise(new AccountBecameOverdrawn(this));    }}

This is an important state change — part of the business’s ubiquitous language that might have further implications down the line e.g. incurring overdraft fees. Udi Dahan writes a lot on this topic — it is a big help in decoupling your domain model, and is is the basis for event-sourcing CQRS.

So hopefully that starts to gives you an idea of what state is all about — more than just data!

Null Object pattern for a WPF ComboBox’s deselected value

Null Object pattern for a WPF ComboBox’s deselected value

Last week, I encountered a problem doing some fiddly UI behaviour in a Prism/MVVM app. I wanted something like this:

I wanted a ComboBox where you can choose one of the available options, or none of them. Null, deselected, whatever.

Unfortunately for me, WPF doesn’t support binding null values in ComboBoxes, ListBoxes or ListViews. Now this is a pretty common problem, and a quick google reveals a few solutions available to this problem:

  • Add an “IsNull” property to your models
  • Wrap the ComboBox in an adapter that provides null support
  • Create an attached property that clears the selected item when the user hits DEL

However, if like us, your domain model is all nicely decoupled through interfaces, the easiest way to get null values into a ComboBox is with the null object pattern. (And thankfully for me doesn’t require any knowledge of WPF control internals to implement).

Here’s what my null object looked like:

public class NullCurve : IFxCurve, IEquatable<NullCurve>{    public string Name { get { return ""; } }    public void DoStuff() {} // Has no implementation    // Note the equality overload. Null objects are value types -- they    // have no identity, and are all equal.    public bool Equals(NullCurve other)    {        return other != null;    }    public override bool Equals(object obj)    {        return Equals(obj as NullCurve);    }    public override int GetHashCode() { return -1; }}

To use it, you simply pop a null object at the start of your list. And check whether it was selected on submit:

public class FxCurveSelectionViewModel : ViewModelBase{    public ObserableCollection<IFxCurve> AvailableCurves { get; private set; }    public IFxCurve SelectedCurve { get; set; }    public FxCurveSelectionViewModel(ICurveRepository curves)    {        AvailableCurves = new ObservableCollection<IFxCurve>();        AvailableCurves.Add(new NullCurve());        AvailableCurves.AddRange(curves.GetAllCurves());    }    public void Submit()    {        if (SelectedCurve.Equals(new NullCurve()))            // nothing was selected    }}

XAML binding is standard; no need to change anything because we handle it all in the view model. Which arguably is not the most DRY solution long-term, but sufficient until I learn more about WPF internals to do it elegantly with XAML.

NDesk.Options: getopt for C#

When writing software there are a number of problems which start off simple — simple enough to knock up your own solution — but usually blossom into something much more complex over time.

Logging is one such problem. It starts off with a simple three-liner function using File.AppendText(), but as requirements grow, you need to add things like timestamps, thread-safety, differentiating errors vs informational messages, archiving, and logging to a database. Before you know it, your three-liner logging function has blossomed into a very poor implementation of log4net.

I’ve seen this sort of thing happen often with teams that haven’t had much exposure to open-source library development, but get excited at the opportunity to create some reusable components of their own (which is why you should always be immediately suspicious of internal ‘common’ libraries and ‘custom frameworks’).

The trick is to recognize when the burden of maintaining a home-brew solution no longer makes sense versus integrating an existing library.

In business this is known as build versus buy, and there are of course some situations when it is smarter to build. For example if there are no third-party libraries available in your problem space, or they are immature, or no longer maintained, or they are encumbered with costs/licensing restrictions. Or sometimes you may prefer a unique implementation that actually is better. But all these should be at least recognized and considered before making a decision.

A simple example of this came up last week, when I was developing a command-line tool for running common user scenarios against our system for benchmarking purposes.

One of the intended goals was that we be able to script it into a post-build process, so command-line options were required for verbose logging, repeating scenarios over and over, whether or not to ignore errors, and of course which scenario to run.

Now, like logging, command-line options are not exactly rocket-science. This sort of code is perfectly acceptable:

if (args.Contains("/v")){    // verbose mode enabled}

However this can easily spiral into something far more complex with positional parameters, optional arguments, validation, options that cancel each other, defaults, long options, not to mention supporting both slashes and hyphens.

For this benchmark tool I didn’t even bother writing my own — having used getopt for C and Boost Program Options for C++ in a previous life, I set off immediately to find something similar for .NET.

I ended up selecting NDesk Options, an open-source library for parsing command-line options. It comes from the unix/mono side of .NET where bash still rules supreme, so you know it’s got to be good. And it is. With lambda-based callbacks for each option, and support for just about every command-line switch style known to man, I had the following knocked up in a few minutes:

All that help text is generated automatically for minimal effort. Cool!

Pair programming: Keyboard ninja? Maybe you should drive

As you may know, I’ve recently started at a new position here in London. Last week I was pair programming all day, every day, with a couple of the other developers, learning the ins and outs of the system. It reminded me of an important tip for beginners: good pair programming requires both driver and observer to maintain focus between making a decision and implementing that change.

< p>

Renaming a class or a method can be done throughout your code in a fraction of a second with built-in IDE shortcuts. But something like promoting a static method to an injected service (still a pretty common refactoring) can easily take a couple of minutes to actually do. In this time, there’s not much going on for the observer, except listening to the sound of typing. And waiting. And trying not to get bored.

(If you’re unlucky enough to be paired with me, I’ll probably be completely distracted and playing with all the things on your desk by this point.)

Now, I am no stranger to pair programming, and have used it many times before for small tasks. But this is the first time I’ve ever done it solidly for several days at a time. This past week has been a real eye-opener for me in terms of quickly making code changes; although I have been using ReSharper for a while now, I have a new found appreciation for its keyboard shortcuts, and people who can use them effectively. Which sadly doesn’t include me yet.

Using your mouse to navigate code and poke through menus is just too slow, and it really shows when you are refactoring code in front of someone else. A good driver minimises the lag between agreeing on a change and effecting it with lighting-fast typing skills. So unplug your mouse, and go learn your tools’ keyboard shortcuts!

Correctness vs Robustness

In programming, correctness and robustness are two high-level principles from which a number of other principles can be traced back to.

Correctness Robustness
Design by Contract
Defensive programming
Assertions
Invariants
Fail Fast
Populating missing parameters
Sensible defaults
Getting out of the users way
Anticorruption Layer
Backwards-compatible APIs

Robustness adds built-in tolerance for common and non-critical mistakes, while correctness throws an error when it encounters anything less than perfect input. Although they are contradictory, both principles play an important role in most software, so it’s important to know when each is appropriate, and why.

Robustness

“Robustness” is well known as one of the founding principles of the internet, and is probably one of the major contributing factors to its success. Postel’s Law summarizes it simply:

Be conservative in what you do; be liberal in what you accept from others.

Postel’s Law originally referred to other computers on a network, but these days, it can be applied to files, configuration, third party code, other developers, and even users themselves. For example:

Problem Robust approach Correct approach
A rogue web browser that adds trailing whitespace to HTTP headers. Strip whitespace, process request as normal. Return HTTP 400 Bad Request error status to client.
A video file with corrupt frames. Skip over corrupt area to next playable section. Stop playback, raise “Corrupt video file” error.
A config file with lines commented out using the wrong character. Internally recognize most common comment prefixes, ignore them. Terminate on startup with “bad configuration” error.
A user who enters dates in a strange format. Try parsing the string against a number of different date formats. Render the correct format back to the user. Invalid date error.

(Important side note: Postel’s law doesn’t suggest skipping validation entirely, but that errors in non-essential items simply be logged and/or warned about instead of throwing fatal exceptions.)

In many cases, relentless pursuit of correctness results in a pretty bad user experience. One recent annoyance of mine is companies that can’t handle spaces in credit card numbers. Computers are pretty good at text processing, so wasting the user’s time by forcing them to retype their credit card numbers in strange formats is pure laziness on behalf of the developer. Especially if you consider the validation error probably took more code than simply stripping the spaces out.

Compare this to Google Maps, where you can enter just about anything in the search box and it will figure out a street address. I know which I prefer using.

Robustness makes users’ lives easier, and by doing so promotes uptake. Not only amongst end users, but also developers — if you’re developing a standard/library/service/whatever, and can build in a bit of well thought-out flexibility, it’s going to grant a second chance for users with clients that aren’t quite compliant, instead of kicking them out cold.

Adam Bosworth noted a couple of examples of this in a recent post what makes successful standards:

If there is something in HTTP that the receiver doesn’t understand it ignores it. It doesn’t break. If there is something in HTML that the browser doesn’t understand, it ignores it. It doesn’t break. See Postel’s law. Assume the unexpected. False precision is the graveyard of successful standards. XML Schema did very badly in this regard.

HTTP and HTML are displaying robustness here; if they see anything they don’t recognize they simply skip past it. XML Schema on the other hand fails validation if there are any extra elements/attributes present other than precisely those specified in the XSD.

Correctness

So robustness makes life easier for users and third-party developers. But correctness, on the other hand, makes life easier for your developers according to the books on software development methodologies — instead of bogging down checking/fixing parameters and working around strange edge cases, they can focus on the one single model where all assumptions are guaranteed. Any states outside the main success path can thus be ignored (by failing noisily) — producing code that is briefer, easier to understand, and easier to maintain.

For example, consider parsing XHTML vs regular HTML. If XHTML isn’t well formed, you can simply throw a parser error and give up. HTML on the other hand has thoroughly documented graceful error handling and recovery procedures that you need to implement — much harder than simply validating it as XML.

Which should you use then?

We have a conflict here between robustness or correctness as a guiding principle. I remember one paralyzing moment of indecision I had when I was a bit younger with this very question. The specific details aren’t important, but the 50/50 problem basically boiled down to this: If my code doesn’t technically require this value to be provided, should I check it anyway?

To answer this question, you need to be aware of where you are in the code base, and who it is serving.

  • External interfaces (UI, input files, configuration, API etc) exist primarily to serve users and third parties. Make them robust, and as accommodating as possible, with the expectation that people will input garbage.
  • An application’s internal model (i.e. domain model) should be as simple as possible, and always be in a 100% valid state. Use invariants and assertions to make safe assumptions, and just throw a big fat exception whenever you encounter anything that isn’t right.
  • Protect the internal model from external interfaces with an anti-corruption layer which maps and corrects invalid input where possible, before passing it to the internal model.

Remember if you ignore users’ needs, no one will want to use your software. And if you ignore programmers’ needs, there won’t be any software. So make your external interfaces robust. Make your internal model correct.

Or in other words: internally, seek correctness; externally, seek robustness. A successful application needs both.

Announcement: I’m moving to London!

Announcement: in just over a fortnight I’ll be packing my bags to go chase the kiwi dream – I’m moving to London!

Provoke has been a wonderful home for the past two years, and I thank all my workmates and clients who made my time there so special. Working here has really been an unforgettable experience, and I hope to take a little bit of that magic onto future jobs and organisations.

So far, my immediate plan for the next few months involves .NET architecture/development work in London, probably on contract basis so I can fit in some travel around Europe between projects. I’m also keen to check out the various developer conferences like QCon and Oredev. But first, I need to start packing!

Domain-Driven Documentation

Here’s a couple of real-life documentation examples from a system I’ve been building for a client:

Monitored Individual is a role played by certain Employees. Each Monitored Individual is required to be proficient in a number of Competencies, according to [among other things] what District they’re stationed in.

Training Programme is comprised of Skills, arranged in Skill GroupsSkill Groups can contain Sub Groups with as many levels deep as you like. Skills can be used for multiple Training Programmes, but you can’t have the same Skill twice under the same Training Programme. When a Skill is removed from a Training ProgrammeIndividuals should no longer have to practice it.

This is the same style Evans uses himself in the blue DDD book. A colleague jokingly called it Domain-Driven Documentation.

I adopted it after noticing a couple of problems with my documentation:

  • I was using synonyms — different words with the same meaning — interchangeably to refer to the same thing in different places.
  • Sentences talking about the code itself looked messy and inconsistent when mixing class names with higher-level concepts.

It’s a pretty simple system. There are only three rules to remember: when referring to domain concepts, use capital letters, write them in full, and write them in bold.

Highlighting the names of domain concepts like this is a fantastic way to hammer down the ubiquitous language — the vocabulary shared between business and developers.

Since adopting it, I’ve noticed improvements in both the quality of my documentation, and of the communication in our project meetings — non-technical business stakeholders are starting to stick to the ubiquitous language now, where in the past they would fall back to talking about purely UI artifacts. This is really encouraging to see — definitely a success for DDD.

jQuery: checkboxes that remember their original state

Last week I had to write a little javascript for a form that involved a long list of check boxes. To save time, the application only processes rows where the checkbox value actually changed away from its original state.

For example, if a checkbox was checked to begin with, then the user unchecks it then re-checks it, we don’t have to do anything because although it did change, it ended up back at the same original state.

This is pretty easy to achieve by remembering the original state of the checkbox using jQuery data — library methods for storing arbitrary javascript objects in DOM elements — then comparing against the original value when toggled.

<script type="text/javascript">        $(document).ready(function() {                // Set aside the original state of each checkbox.                $("input.toggle").each(function() {                        $(this).data("originallyChecked", $(this).is(":checked"));                });                                // Check whether it really changed on click.                $("input.toggle").change(function() {                        var action = $(this).siblings("span");                        if ($(this).data("originallyChecked") == $(this).is(":checked"))                                action.text("(no change)");                        else                                action.text($(this).is(":checked") ? "added" : "removed");                });        });</script><ol>        <li>Apple <input type="checkbox" class="toggle" /> <span/></li>        <li>Banana <input type="checkbox" class="toggle" checked /> <span/></li>        <li>Carrot <input type="checkbox" class="toggle" /> <span/></li>        <li>Zucchini <input type="checkbox" class="toggle" checked /> <span/></li></ol>

The next requirement was adding a select/deselect all button. This proved a little bit more difficult, because of the way jQuery deals with events and the checked attribute. To cut a long story short, I ended up with an event handler that manually sets the checked attribute and then fires the change event on all the checkboxes (I tried the click event first, but it didn’t seem to pick up the new state).

$(document).ready(function() {        $("input#select-all").click(function() {                $("input.toggle").attr('checked', this.checked);                $("input.toggle").change();        });});

Altogether, it works very nicely in only a few lines of javascript.