On my current project we have decided to appease my sensibilities and have called these Cross Functional Requirements to better express what they truly represent – requirements which cross all the functions we are building. So far the wording works – but we have only finished the 2nd week of inception.

The English language is a very complex beast which can easily strike confusion in the most unsuspecting moment. Take, for example, the word “lollies”. Did your mind immediately jump to a bag of gummy bears, redskins, bananas or milk bottles that you get from the garage? Or instead did you start thinking of a frozen dessert on a stick? If you thought the former, then, like me, you probably are Australian. Because the English term for it is sweets, and the American version is candy (although I doubt that they have such wonderful lollies as bananas and milk bottles). And the frozen-dessert-on-a-stick – thats an iceblock for me!

Take another example – when Sisqo’s Thong Song came out I didn’t really understand why someone dedicate an entire song to $1 rubber plugs – until I watched the video clips and I realised that he wasn’t referring to “flip flops“.

The lesson that I have learnt living in the UK is that I have to be very careful with the words that I use, lest I cause confusion by saying that someone was running around with their pants* off**.

And this is also applies to the words and language that we use around our business, between developers and in our code. Too often we describe concepts by words like “that thing” or “this stuff” which can obfuscate what it really is, and hence hinder our ability to model it. I often see complexity, misunderstandings and hacks creep into code bases when the original designer has referred to an information concept as “this thing” without taking the time to name it. I find that spending the energy talking to the business to understand what you are really producing helps clarify understanding which in turn distills the model into a simpler, easily understood model.

I had this demonstrated to me yesterday, when I came across a pair discussing how to “shove” this concept of “a thing that when clicked on opens up a popup with stuff in it” onto the model. As I listened to the conversation, I noticed just how muddled the model and the situation was becoming, so I decided to intervene with some of my words of wisdom about what they were trying to model. As soon as we worked out that the “thing that when clicked on opens up a popup with stuff in it” translated into “a help message”, we were easily able to see exactly where in our model it should go.

So, never underestimate the power of the words we use. When faced with a confusing concepts strive to distill it into easily understood, well defined names.

* pants in Australia are trousers – pants in the English vernacular are what I call underpants.
** yes I have once said that at work after I saw a pair of jeans on the table and was a little confused by what someone must be wearing!

So, the code started with:

private bool hasVehicle;

then, by following Coding Tip #27, went to:

private Vehicle theVehicle;
public enum Vehicle
{
    Car,
    MotorBike,
    PeopleMover
}

and now can turn into:

private Vehicle theVehicle;
public class Vehicle
{
    public static Vehicle Car = new Vehicle("Car");
    public static Vehicle MotorBike = new Vehicle("MotorBike");
    public static Vehicle PeopleMover = new Vehicle("PeopleMover");

    private Vehicle(string name)
    {
        this.name = name
    }
    private string name;
}

so my objects are all setup to add additional functionality:

private Vehicle theVehicle;
...
theVehicle.WillSeatAPartyOf(4);
...
public class Vehicle
{
    public static Vehicle Car = new Vehicle("Car", 5);
    public static Vehicle MotorBike = new Vehicle("MotorBike", 2);
    public static Vehicle PeopleMover = new Vehicle("PeopleMover", 8);

    private Vehicle(string name, int passengerLimit)
    {
        this.name = name
        this.passengerLimit = passengerLimit;
    }
    private string name;
    private int passengerLimit;

    public bool WillSeatAPartyOf(int numberOfPassengers)
    {
        return numberOfPassengers =< passengerLimit;
    }
}

I debate whether the class should contain the name or the index, usually I use the name; you can use both. Obviously if someone was now relying on the enum order, you would need to give it the index. Another advantage of this is because the constructor is private, you know that there are a definitive list of representations for it.

I don’t usually use class straight away. Indeed, I usually take bets to see how long it will stay an enum – sometimes the refactor is immediate, other times it remains an enum.

The problem we faced with doing so is the same problems I think most people face : eventually, your domain wants to take your model in one direction, and your relational database wants to take it in another. Personally, I really like Domain Driven Design – I like my objects to be reflective of the domain – and I don’t really care about how the database stores them, or indexes or stuff like that (I seem to remember something about BNF back in uni), so I am more inclined to let my model move towards the domain; but I do understand that there are consequences in doing so when looking at how my data is accessed.

I have now come to the belief that there is value in having my domain models but equally having ORM models. More so, I have decided that (despite the perceived increase in classes) there is a true distinction between the two and should be implemented as two separate classes. You can see from my examples what I am talking about, but basically my domain model knows nothing about the ORM model and anyone (apart from the necessary repository) knows about it either. The ORM model is used by the repository of concern as a helpful tool for it to store to the database; it could equally be done using SQL.

# The Domain model - yes there is more to it than that
class RegistrationForm

  def initialize(key)
    @key = key
    @name = ""
    @email = ""
  end
  ...
end
# The repository to find/save a registration
class RegistrationRepository

  def find(key)
    registration = find_registration(key)
    form = RegistrationForm.new
    return form unless registration
    update_form(form, registration)
  end

  def save(form)
    registration = find_registration(form[:key])
    registration = create_registration unless registration
    update_registration(registration, form)
    registration.save
  end

  private

    def find_registration(key)
      registration = Registration[:id => key]
     # This is the sequel equivalent of Registration.Find(key) in ActiveRecord
    end

    def create_registration
      registration = Registration.new
      registration
    end

    def update_form(form, registration)
      form.update(
        :key => registration.id,
        :name => registration.name,
        :email => registration.email)
      form
    end

    def update_registration(registration, form)
      registration.name = form[:name]
      registration.email = form[:email]
    end
end
# The ORM representation (using Sequel as my ORM library)
class Registration < Sequel::Model
  set_schema do
    primary_key :id
    varchar :name
    varchar :email
  end
end

Maybe this is something that other folk have already thought of, and I am just catching up, but the proliferation of web MVC style frameworks which mandate persistence layers (eg Rails) makes be think that this may need to be revisited.

As much as refactoring tools like resharper help you out, when it comes to refactoring a bool into an enum, it’s a pain in the arm. One of these pain points being that quite often, you see:

if (fieldRepresentedByBool) {}

which makes it quite annoying to turn it into:

if (fieldNowRepresentedByEnum.Equals(Enum.True))

Another pain point is refactoring your database is not much fun, especially if you have to ensure that you also migrate data.

The other benefit that you get from enums when compared to booleans is that your method signatures are more expressive. Consider these two signatures (yes, I know completely contrived, but I couldn’t think of a better example), and tell me which one you prefer.

render(foo, true) // where true represents isVisible
render(foo, Display.Visible)

So, next time you start to type bool think about using an enum instead.

The problem is that they see the order that stories should be developed in should mirror the process flow of the tasks that the customer needs to take; after all, you can’t buy an item without choosing what you want to buy and you can’t buy anything before you login. This might also be due to the stories revolving around the tasks the user needs to undertake instead of the goals they are trying to achieve.

Now,  if I was to build a classic shop-on-line website, the first story that I would start with would be to implement a page which accepts payment information and a Buy Now button in the middle of the page. What is the customer going to buy? The same product that every other customer will buy. Now, this does not seem to be that fantastic for the user – they don’t even have a choice in what they are buying, but this is actually the best place to start because it is not the As a Customer I want to buy a book So that I can learn new stuff story that we are implementing; it is the As a Business Stakeholder I want customers to buy my products So that I can make a living story. By defining our stories based on goals, and ordering the development based on what is more valuable, we can launch our site with only one story complete and still make money.

Now, lets go back to the beloved login story. One thing that I hate is a website which puts up a high barrier-to-entry before I can buy a product. At a real-life store, they don’t make me fill in a form to say who I am before I can buy my Big Mac meal; there is no real-world equivalent to the login functionality. What is the real reason that I as a customer needs to login? Where is the value? What is their goal? The next story in this area that you could play would be As a Customer I want to view my purchse order in an email So that I can keep a record of the payment. This story could just involve a text field where the user enters their email address if they wish to receive the email receipt (remember, back in the day, receipts from over-the-phone sales would be sent in the post). Again, we can go live with this and we are still not requiring the customer to login.

The final goal that summaries the customers experience is that As a customer I would like the computer to do some work and remember their details So next time I make a purchase, I only need to place items in the basket and checkout.  All this requires is the customers email address (a perfect URN by the way – why would you even think about having usernames???) and a password. Importantly, however, the gathering of this information does not need to occur before they purchase their items! It can happen at the end of the transaction, thereby allowing the customer to complete their goal (purchasing their items) without hinderence. 

The customer’s goals are now met, and the business stakeholder’s goals were met in the very first story, it is only the marketers’ goal of wanting to capture information about the customers on the site which has not been met. Usually marketting departments ask that the customers complete a 4 page registration form, in order for customers to register (As a marketer I want to know information about our customers So that I can target our features to meet their needs). But, what value or incentive is there for the customer to fill in this information? To appease both our market departments, and our customers, however, we could incentivise the customers by rewarding bonus points which go towards their next purchase for completing their registration form. But also importantly, this does not stop the customer from spending money on your site.

So, next time you go to add a login box on your site, think about what the customers true benefits are.

Dan’s point of view is that in order to be good citizens, our methods should form around interfaces and not rely on the concrete representation, after all if you need the data as a list, you can always create a new one.

My argument is that the IList interface is so rubbish that you would always need to create a list in order to manipulate it, and then that just becomes noise.

Both sides of the argument have valid points, and valid critisisms. After a little searching, we have found the answer: use extension methods for IList to add the fantastic list methods to the interface. In fact, we have gone one step further, and added extention methods to IEnumerable, so that we can have the power for our dictionaries as well. We have taken the opportunity to add a lot more functional methods  such as Head, Tail, Exists,  Find and AsString.

Here is an exerpt from our class.

    public static class EnumerableExtensionMethods

    {

        public static void ForEach<T>(this IEnumerable<T> source, Action<T> action)

        {

            foreach (T t in source)

            {

                action(t);

            }

        }

 

        public static List<T> ConvertAll<S, T>(this IEnumerable<S> source, Converter<S, T> converter)

        {

            return new List<S>(source).ConvertAll(converter);

        }

 

        public static List<T> FindAll<T>(this IEnumerable<T> source, Predicate<T> predicate)

        {

            return new List<T>(source).FindAll(predicate);

        }

    }
<div>