Do not punish the consumer with exceptions

We all write code an we all consume other peoples code. I know that it is easier to put your brain on autopilot and just throw exception for every minuscule thing that the consumer does wrong. But we should not. If we can fail gracefully or even recover from invalid input or internal errors then we should do so.

Take the following code as an example:

public IEnumerable<Product> GetProducts(IEnumerable<Guid> productIds)
{
  if(!productIds.Any())
    throw new ArgumentException("At least one id must be passed");

  // Getting the products from the database and...
}

I find this code a little hars on the consumer. If he passes an empty list of ids he gets an ArgumentException. I think that this code can be made friendlier for the consumer.

<pre>public IEnumerable<Product> GetProducts(IEnumerable<Guid> productIds)
{
  if(!productIds.Any())
  {
    Log.Warning("Method called with empty list. Returning empty list as result");
    return new List<Product>();
  }

  // Getting the products from the database and...
}

In this case the consumer will get a empty list of products and he can continue. If it becomes apparent that the consumer made a mistake. You can look into the logs and see what happened.

I think that this is much more user friendly.

Building a .net solution using RAKE [part 2]

As begone in the previous post lets look at the RAKE script.

Preparing the build

The first thing the script has to do is to initialize the file structure it is going to work with later on in the script and there are some global variables to set. And before you look at the code this is the biggest task in the build script.

task :prepare do |taks, args|
 require 'fileutils'
 require 'ftools'
 FileUtils.rm_rf Variables::OUTPUT_PATH if File.exist? Variables::OUTPUT_PATH
 Dir.mkdir(Variables::OUTPUT_PATH)
 Dir.mkdir(Variables::SOURCE_PATH)
 Dir.mkdir(Variables::WIKI_PATH)
 Dir.mkdir(@RELEASE_PATH = "#{Variables::OUTPUT_PATH}/#{Variables::PROJECT_NAME}_#{args["version"]}")
 Dir.mkdir(@DOCUMENTATION = @RELEASE_PATH + "/Documentation")
 Dir.mkdir(@VALY = @RELEASE_PATH + "/Valy")
 File.copy('nunit.xsl', "#{Variables::OUTPUT_PATH}/nunit.xsl")
end

Before we can begin our build and copy bonanza we have to prepare some directories into which we want to copy to. Just to avoid all those nasty exceptions later on.

The first to lines “import” some useful things that we require for our IO operations. The fileutils is a IO class that comes with rake and proves extremely useful. So we create a few directories and set the required variables for later use. The last thing we do is to copy the nunit.xsl to the output directory.

If you are wondering what those Variables are then let me disappoint you. There are just constants defined in another file so they do not clog up the main rake script.

module Variables
  ## Project paths
  OUTPUT_PATH = "../Release"
  SOURCE_PATH = "#{OUTPUT_PATH}/Code"
  LIB_PATH = "../Sources/Lib"
  WIKI_PATH = "#{OUTPUT_PATH}/Wiki"

  ## Third party tools
  NUNIT_EXE = "#{LIB_PATH}/NUnit/nunit-console.exe"
  DOT_NET_PATH = "#{ENV["SystemRoot"]}\\Microsoft.NET\\Framework\\v3.5"

  ## Build properties
  CONFIG = "Debug"
  PROJECT_NAME = "valy"
end

Getting the sources from the repository

As mentioned before valy is hosted with Google code in a mercurial repository. To make my life (and the scrip) easier I have tortoiseHG installed locally.

So let’s take a look at the script that gets my sources from the repository

desc "Gets the sources from the valy repository"
task :get_sources => [:prepare] do
   Helpers.clone_repository("https://valy.googlecode.com/hg", Variables::SOURCE_PATH)
   Helpers.clone_repository("https://wiki.valy.googlecode.com/hg/", Variables::WIKI_PATH)
end

To make it easier the Helper module defines a method clone_repository that looks quite simple.

# Clones the given mercurial repository
def Helpers.clone_repository(repository_path, output_path)
  puts "Cloning repository #{repository_path}"
  unless system "hg clone #{repository_path} #{output_path}"
    puts "Clone FAILED"
    puts $?
  end
end

I must say that I like this piece of code. It’s simple and effective. I take advantage of the fact that I can do a system call to hg and it will get the repository for me. I am using the system command for this because it returns a boolean and in the case of failure stores the error message in the $? global variable.

And that’s it. Now you have the sources on your local system.

Building the solution

This is actually represented in two tasks:

1. Set the version number in the assemblyinfo.cs
2. Build the solution using MsBuild

The two tasks again look “quite” easy.

task :set_assembly_attributes => [:get_sources] do |task, args|
  Helpers.set_assembly_version "#{Variables::SOURCE_PATH}/Sources/valy/CommonAssemblyInfo.cs", args["version"] if args["version"]
end

desc "Compile solutions using msBuild"
task :compile=> [:set_assembly_attributes] do
  solutions = FileList["#{Variables::SOURCE_PATH}/**/*.sln"]
  solutions.each do |solution|
   Helpers.build_solution(solution)
  end
end

Both tasks depend on the Helpers module that we will look at later. For now lets concentrate on the task at hand

The :set_assembly_attributes task is the only rake task (until now) that uses parameters represented by the args in the task block. So if the version is not given the default version will remain at 0.0.0.0. To illustrate lets look at some calls to the rake script:

c:\valy\build>rake version=1.0.0.1
=> dll version = 1.0.0.1

c:\valy\build>rake
=> dll version = 0.0.0.0

Before we look into how I set the assembly version let me state that I have seen all the libraries and custom task out there and found them to complicated form my purpose. So just 4 the fun of it I did it my way.

def Helpers.set_assembly_version assembly_info_file, version
  unless File.exist? assembly_info_file
    raise "File #{File.extend_path(assembly_info_file)}, not found";
  end
  buffer = ""
  buffer = File.open(assembly_info_file, 'r'){|f| f.read.gsub(/0.0.0.0/, version)}
  File.open(assembly_info_file, 'w'){|f| f.write buffer}
end

As is visible from the code above I use a simple regex replacement to change all occurrences of 0.0.0.0 to whatever I provided the script as the version. It is not perfect nor pretty. What I hate the most about it is the fact that I need the buffer, I would rather read and write in one single stroke. But this will do for now.

After seeing the clone_repository method the build_solution is no big surprise.

def Helpers.build_solution solution_path
  puts "Building solution : #{solution_path}"
  if system "#{DOT_NET_PATH}/msbuild.exe /noconlog /nologo /p:Configuration=#{CONFIG} #{solution_path} /t:Rebuild"
    puts "Build SUCCEEDED"
  else
    puts "Build FAILED"
    puts $?
  end
end

Looks familiar? Well it is. This is the first indication that I will have to refactor this in the future to make it “prettier”. But for now it works.

Running unit tests

This final tasks is not yet complete. After the tests are run the xml output is not transformed into HTML using the XSL file provided at the beginning But the rest of the task looks as following.

desc "Testing the build assemblies using NUnit"
task :test => [:compile, :prepare] do
  tests = FileList["#{Variables::SOURCE_PATH}/**/*tests.dll"].exclude(/obj\//)
  Helpers.run_tests tests, Variables::OUTPUT_PATH + "/TestReport.xml" unless tests.empty?
end

As mentioned before this is still work in progress…

Basically what happens is that I search for all Dlls which names end in tests and exclude the ones found in the obj folders.

Enter the Helper that actually runs the tests.

def Helpers.run_tests tests, report_file
  puts "Running tests"
  system "#{NUNIT_EXE} #{tests} /nologo /xml=#{report_file}"
end

Basically just runs the nunit console command with some parameters. So nothing special here. Yet.

And that is all I prepared for this post. Next time we will look at how I:

• Get the test coverage
• Harvest the build files
• Package them into a zip file

thx for reading.

Building a .net sollution using RAKE

When working on a project you do accept that you have to do some choirs that you would rather not. When working on something “just4fun” this same assumption is just not true. If I am spending my free time behind the computer then I want to do things that I want to do. One of those things that I hate to do are reports and deployment packages.

The sad truth is that you need both. So what can you do about it? From my standpoint you have two options:

1. You just do it by hand and bear the pain
2. Automate it!

As “The pragmatic programmer” and “The productive programmer” are teaching us automation is the way to go! So we have to look at build automation. In the past I would just open a text editor and start typing a ANT build script. But for valy I wanted to do something new. And the reasons why I wanted to get from ANT are the following:

• XML is good for structuring data but are really bad when trying to capture a process
• It is quite hard to get a reasonable structure into the XML file
• It takes quite some experience to reasonably read the ANT file

I hope you get the general idea that XML is not a good way of describing a build process. ANT is a great tool but the XML format is killing it for me (hope they provie a DSL in the future).

So after long consideration I opted for RAKE. Rake is a Ruby based DSL for build automation. If you have ruby installed then getting RAKE is as simple as installling an addition gem. But setting up RAKE is not a part of this post.

After opting for RAKE I had to determine what my build script will do and if I will have more than one to get the job done. Some hours later I came up with the following list of tasks it has to do:

1. Get sources from the mercurial repository
2. Build sources
3. Run tests
4. Run nCover
5. Assemble documentation
6. Create a deployment package
7. Compress
8. …

Not exactly mission impossible but still a challenge.

Before we continue let’s get something clear. The scripts posted here are still work in progress and my change. If you want to follow my progress, all scripts are published at http://code.google.com/p/valy/source/browse/#hg/Build. And ofcourse you can copy and use at your delight, just let me know if you made some improvements.

I will not use any words on how I structured the code because I lost to many words already

Because this post is getting quite long I have decided to break it into multiple posts.

So until next time.

Dynamic object activation, the cool way

After working with ASP.NET MVC for some time I learned to love and appreciate the little things in the framework that are done really well. One of those, that sticks out in my view, is the way that the HTML attributes are passed to view items.

Html.TextBox("UserName", Model.UserName, new {@readonly = "readonly"})

I personally think that the new {@readonly = “readonly”} syntax has something interesting. The potential usage of this are quite mind-blowing . I intend to create a generic validator activator in the near future, for now I just implemented a simple test instance initialization.

In valy a validator is initialized by providing a validation initialization contexts. One of the key components of this is a dictionary which is then used to setup the validator state (more about this in a later post). What I wanted was a streamline syntax to initialize a validator for unit testing. The original implementation of this was something like the following:

var validator = new StringInRange(new Configuration.Confiuration{Message = "Error message", ThrowException = true, Parameters = new { { "MinValue", 1 } }});

Not really that “sexy”, and I wanted to make it sexy. So I turned to our old friend reflector and took a closer look at how it is done in the ASP.NET MVC framework. What came out is the following.

[Test]
public void Validate_PassInRangeString_ValidationPasses()
{
  var validator = TestHelper.Create<string, InRange>(ERROR_MESSAGE, false, new { @MinLenght = 3, @MaxLenght = 7 });

  var results = validator.Validate(IN_RANGE_STRING);

  results.Passed();
}

This gives us a nice little unit test that is neatly separated into a setup, action, assert sections. Or in the more modern therms: Given, when, then.

And I think that this is quite simple and straight forward. There are some problems with this implementation but still I think that it is a great start.

To come now to the interesting side of the implementation. Here is the implementation of the Create method.

public static IValidator<T> Create<T, TValidator>(string message, bool throwException, object parameters)
{
  var parameterDictionary = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);

  if (parameters != null)
  {
    foreach (PropertyDescriptor descriptor in TypeDescriptor.GetProperties(parameters))
    {
      object value = descriptor.GetValue(parameters);
      parameterDictionary.Add(descriptor.Name, value);
    }
  }

  var configuration = new Configuration.Confiuration
  {Message = message, ThrowException = throwException, Parameters = parameterDictionary};

  return (IValidator<T>)Activator.CreateInstance(typeof(TValidator), configuration);
}

If you are wandering what happens behind the scenes let me explain.

Behind the scenes a dynamic object is created with the properties MaxLenght and MinLenght. When the Create method gets this dynamic object all I does is to iterate through all the public properties and create a Dictionary where the property names are the keys and the property values become the values of the dictionary. This dictionary is then passed to the validator constructor and all is well again.

I intend to make this Object -> Dictionary step unnecessary by providing a constructor overlay that will handle this dynamic object. But this is still in the future.

What has to be mentions is that there is a problem with this. At least I have a problem. And that is when I want to set a property of the type System.Type. The problem is that the property does not get set to type System.Type but to System.RuntimeType. But this is a minor setback that should be solved in the near future.

All in all this is a great way to make unit tests simpler.

Validating a validator

If you take your precious free time and build a validation framework from the ground up you want the architecture to be perfect, or as close to perfection as possible. So you are bound to run into some problem on the way there. The problem that I was struggling with a while ago was the question hot to validate the validator?

The problem became painfully obvious when I wrote the first System.String validator that required some external configuration. To illustrate my little dilemma here is the validator code.

namespace valy.Validators.String
{
 public class Regex : BaseValidator<string>
 {
   public Regex(IEnumerable<IValidator<string>> validationParts) : base(validationParts){}
   public Regex(IValidatorConfiguration configuration) : base(configuration){}

   protected override IValidationResult DoValidate(string objectToValidate)
   {
     if (reg.IsMatch(objectToValidate, RegularExpression))
       return Pass();
     return Fail(ValidationFailReasons.Invalid);
   }

   protected override void CheckParameters()
   {
     Require(this, v => v.RegularExpression, s => !string.IsNullOrEmpty(s));
   }

   public string RegularExpression { get; set; }
 }
}

For now try to ignore the existence of the CheckParameters method.

In this special case I have to validate that a valid non-empty regular expression is given to the validator. You could do it in the validation body with a simple if statement, but then it would be in the responsibility of every validator to do it’s internal validation and communicate possible violations to the external world. This would lead to a incosistent framework in no time at all. What I wanted was a way by which the validator could define a set of rules that had to be met before the actual validation could happen.

This does not give us complete protection. In the above example the object to validate can still be null. But that is not a problem of the validator anymore.

But lets return to the method that you should have ignored until now. The CheckParameters methods purpose in live is to define a set of rules that ensure that the internal state of the validator is consistent. This means that if the method “passes” the validator is ready to use and will not throw any bogus exception if invoked.

The core of this internal validation scheme is the Require method implemented in the base validator. Using this simple building block you can put together relatively complex validation schemes like show in the next code sample.

protected override void CheckParameters()
{
 Require(this, v => v.MaxLenght, i => i > MinLenght);
 Require(this, v => v.MinLenght, i => i < MaxLenght);
 Require(this, v => v.MaxLenght, i => i > 0);
}

The complexity of the example above will not win you and noble prizes but will ensure that your range validator can not be given an invalid range. And this works for me(until now)!

This is not perfect and the thing that is annoying me the most is the fact that the current object has to be passed as a parameter to the function. This is necessary because the Require method is defined on the parent class and therefore has to somehow link to the actual overriding class. But this is just a minor hiccup. There are other potential problems that are not causing me any headaches yet, so they will get fixed when they start to hurt.

All in all this scheme works and I am quite happy with it. The last part I would like to show you is the implementation of the Require method.

protected void Require<TValidator, TParam>(TValidator validator, Expression<Func<TValidator, TParam>> property, Expression<Predicate<TParam>> predicate)
{
 var propertyValue = property.Compile().Invoke(validator);
 if (!predicate.Compile().Invoke(propertyValue))
   throw new ValidatorInitializationException(
             string.Format("Validation inicialization failed on predicate : {0} for member : {1}",
             predicate.Body, property.Body),
             GetType());
}

As you can see the implementation is nothing special. Just two functions that the evaluated at runtime and if predicate fails a ValidationInitializationException is thrown. Really there is nothing more to say about this topic.

Hope that this helped someone out there and if someone out there seas something wrong with this write a comment and tell me about it.

Constraint-Based Asserts and NUnit

In this post I will concentrate on NUnit and it’s “new” feature. Well not exactly new,  but a feature that are around since version 2.4 (current version is 2.5.2). This feature, that I would like to present here, is the constraints based assertion.

Before we start with the new and shiny let’s look at the old and proven.

[Test]
public void FooTest()
{
  var result = DoSomething();

  Assert.AreEqual("something", result.Text);
}

This is what we know and this is what we work with. The problem is that people manage to confuse the expected and actual parameters of the assert statement. Which then results in funny little mishaps. But this is not the theme of this post.

What I would like to show here is the constraint based assertion. To get us into the subject here is a little example.

[Test]
public void FooTest()
{
  var result = DoSomething();

  Assert.That(result, Is.EqualTo("something"));
}

Looks nice and it is. What I find good is that it gets harder to confuse the expected and actual values.

The best thing is that you can chain the constraints. This would then look like the following.

[Test]
public void FooTest()
{
  var result = DoSomething();

  Assert.That(result, Is.Not.EqualTo("gnihtemos"));
}

The next thing is not really in context with the posts title but I think that it is such a nice feature that it is worth mentioning. The “thing” in question is the exception assertion. To get the record straight I find nothing wrong with the ExpectedExceptoin attribute but this new version is just cleaner.

So as before lets look at the old and proven before we take a look at the new and shiny. The old and proven would look like this.

[Test]
[ExpectedException(typeOf(SomeException))]
public void ExceptionTest()
{
  ThrowsSomething();
}

This is nice and nicely extendable. What they came up with is a non attribute version that works really well.

[Test]
public void ExceptionTest()
{
  Assert.Throws<SomeException>(() => ThrowsSomething());
}

This is nice and becomes quite readable without being to invasive. And I personally quickly fell in love with this way of testing for exceptions.

With this much goodness there has to be something bad. And there is. What you will find hard to do is to integrate your custom constraints into NUnit. You actually have two variants how to use your custom constraints without poking into the framework itself.

Option one is to use a build in construct and get code that would look something like this.

[Test]
public void MyCustomConstraintTest()
{
  MyObject result = DoCustomStuff();

  MyConstraint constraint = new MyConstraint();
  Assert.That(result, Has.Some.Matches(constraint));
}

And option two which requires less code but does not look that good.

[Test]
public void MyCustomConstraintTest()
{
  MyObject result = DoCustomStuff();

  Assert.That(result, new MyConstraint(););
}

There is always the option to hack at the framework and integrate your custom constraint. But I would not recommend it.

As a last thing lets take a look at how you can write your own constraint. It is actually quite simple. All you have to do is to derive from the Constraint class. The base class itself is abstract and features many methods that you can override. But in most cases you will just need the two abstract ones.

Your custom constraint could look something like this:

public class MyConstraint : Constraint
{
  public bool Matches(object actual)
  {
    if(actual is MyObject)
      return ((MyObject)actual).Quantity > 0 ? true : false;
    return false;
  }

  public void WriteDescriptionTo(MessageWriter writer)
  {
    writer.write("MyConstraint failed");
  }
]

So this is the gist of it. I hope that you got a little insight into the new features of NUnit.

All that is now left to do is to use it

Configuration entropy

The term software entropy is coined and the definition of it can be found here. I would like you to take into consideration the term configuration entropy.

Because of the increased complexity and forever changing requirements the way we write software has changed. In the past we could try and “one up” each-other by coding the same piece of logic in every project we worked on. This option has become impractical and dangerous. Dangerous because we tended to write half baked software that was just not up for the challenge. And to be honest I do not want to write a data access layer or DAL everytime, I just want to solve problems in my problem domain and not in all others that happen to be in my way.

To make the long story short: we are having more and more configuration in our applications. If you have to work on a compiled language you will notice quite quickly that once that a peace of code leaves the safe area of your test environment it usually developes some problems. And usually that results in an recompile and redeploy… So this is quite a big intensive put more “stuff” into configuration files.

So what does this mean? This means that you will reach a point where the configuration becomes more, and more complex than your actual code. The unit testing world has already proven that unit tests are part of our code and that they deserve the same tender attention and care as code itself. The same goes for all of that configuration. If you do not constantly watch after all the configuration out here you will get overrun. And when this happens you will have a BIG problem.

When you can’t tell where those mysterious values are coming from then my friend you are really at the heart of the configuration entropy zone. And getting this situation under control will require quite some effort. So we should avoid it at any cost.

In my experience the best way to do this to divide and conquer. This is achieved by following the following steps:

1. Ignore the existence of the appSettings section in the app.config/web.config file
2. Configure once, use often
3. Write custom configuration sections!! <- How this is done later on
4. Lose the idea that all configurations are stored in one file
5. All configuration that can be put in a separate file should be put in a separate file
6. Do not place configuration in code <- only partially true

Ignore the existence of the appSettings section

The developers in Redmond were so nice as to give as a common and easy to use place where to put all our application configurations. This sounds great but is really a curse. Why? Because after some time you will notice that it gets hard to manage. You will spend more cognitive effort trying to remember how the configuration key is called and to validate if the configuration value is really what you expect. In the configuration API all is an object by default so there is no easy way to determine if the value given is really a number or just a bogus string.

And from my personal experience this section tends to get big (100+ entries) and environment management gets harder and harder!

Write custom configuration sections

Because we ignore the appSettings configuration section we have to get a suitable substitute. And luckily we have! They are called custom configuration sections. The main advantage of them is that they are type safe. Remember the type validation you had to with the appSettings?

This is the right time to notice that there are two ways of doing this:

1. The “old” way:
   In the old days the custom configuration manager just contained an event handler in which you could/should pars an XML node that contained your configuration section. This is not the prefered way but still gets the job done.
2. The “new” way:
   Today we have a more elegant solution to the problem. Now you have a typed interface to the configuration values in the XML file. Sadly this means sticking to some limitations of this implementation.

What you want to provide is a custom configuration section for different configuration groups. So for instance all configuration values that have something to do with the configuration of the price calculation logic should be in a configuration group called “Price” or something like this.

A detailed introduction into the world of custom configuration sections will follow in one of the future posts.

Lose the idea that all configurations are stored in one file

In todays flood of configuration values it almost impossible to store all configuration values in one big file. But still this happens, the file in question is usually the web.config or the app.config file. Why? Because they are automagically created by the project wizard. This is not bad for some cases but if the configuration of your application gets really heavy you will feel the burn. Maintenance will become a nuisance because the file will be just to big to manage.

So what do we do about this? The simplest and most logical solution is to use an algorithm that we all learned in school: “Divide and conquer”. By this I mean that you should put all configurations that can be in own files into own files. The prime candidate for this are log4net and Spring.net. Both can be put in own configuration files quite easily.

What do you gain by this?

1. The configuration does not clog your app.config or web.config file anymore, leaving room for more vital configuration to be there
2. When you need to change the configuration (for example having different logging configurations for test and live) you do not have to manipulate a complex XML file but just replace a file which is much more easily done
3. You have different components in different configuration files, thus eliminating the need to feverishly scroll and look for the right section of the configuration file.

I can not put enough emphasis on tis issue. Try to believe me that this is a good thing. Some people may complain that the configuration just got scattered all over the place and that refactoring is now harder to do because of the configuration dependencies. But in the long run the separation will improve you codling skills and help you keep the configuration under control while the project will grow and evolve.

Do not put configuration in code

This is only partially true. Why? Because this rule does not apply to interpreted languages like ruby, python, php (reluctantly calling it a language). Do not be mislead by this. Configuration entropy is as big an issue on the other side of the river as it is here.

So why does the rule not apply to the interpreted languages? Because the whole code is big configuration file. Some will scream now and call me a stupid moron. But thing about it for a minute. In my world the “definition” of a configuration is: A non-compiled part of the application with which the behavior of a routine can be changed without a recompile. And because interpreted languages are not compiled we can change anything in the source-code and continue.

But this is where the problems begin. Because there is virtually no penalty in changing the source-code itself configuration tends to get scattered all around the code. Making it hard to manage the changes made to it. And a clear environment configuration gets quite frustrating when you have to alter multiple files to get the job done. That is why event in those languages I suggest that configuration should be kept in as few places a possible.

Returning back to the world of compiled languages the picture changes. If we stick to my definition of a configuration then all configuration that is stuck in code can not be changed without recompiling the application. Making it quite useless.

The final words

So after this short trip in this topic of configuration entropy I would like you to remember the following:

• Configuration is part of your code, so treat it like this
• Divide and conquer, do not put all your eggs in one basket
• Do not leave configurations in compiled code

A new face

I do not know if it is only me but I need something visual to put on a idea. This is why I am so obsessed by logos. When I start to do something I have to reference it with a visual clue. The same situation is with valy.

That is why the first thing that landed in the repository was the logo. My criteria of how a logo should look like are quite simple:

1. It has to be simple
2. It has to look good in black and white
3. It must be cheap to print or stitch on a peace of clothing
4. I must like it

And looking at the above criteria the original logo was not the best out there. Just to remind you how it looked.

valy logo

Not the most exiting thing in the world. So I asked my sister to help me out here. She is quite a good visual designer and knows what I like. I guess not more than 5 to 10 minutes were spend behind the computer to create the new valy logo.

Take a look and judge for yourself.

New valy logo

I would like to take a second here and thank my sister. If you want to find out more about here you can contact her through me or on facebook.

Validation as it should be in my eyes

public void Foo(string parameter1, string parameter2)
{
	if(string.IsNullOrEmpty(parameter1))
		throw new ArgumentException("parameter1", "Parameter1 should not be null or empty");
	if(string.IsNullOrEmpty(parameter2))
		throw new ArgumentException("parameter2", "Parameter2 should not be null or empty");

	// Actual method logic
}

Seems familiar? Well it should. I bet that in your current project there is at least one method that looks like this. Do you think that this is a good way of validating input parameters? The honest answer is that this approach is not wrong but it has it’s shortcomings:

• If the validation logic changes you will have to recompile the solution
• The validation message is hard-coded
• If you would like to reuse the validation logic you have a major refactoring session before of you
• There is bound to be inconsistency in the validation logic across different methods
• …

The main question here is not what is wrong with this approach but how to make it better.

In my experience as a software developer I have seen many implementation of what could be called a validation framework and used many that are already there. Some are good, very good, but lack some basic functionality. What I expect from a validation framework is the following:

1. Uphold the DBC principle
2. Have a way of defining the validation logic outside the compiled solution source
3. Support IOC
4. Uphold the DRY principle
5. Extendability
6. Optional: Provide a fluent interface for validation setup

DBC

Or design by contract is the α and Ω of a good validation framework. If you want to validate something you have to know what to validate. Some years ago Bertrand Meyer developed this concept for his little language called Eiffel. The idea is to write software that doesn’t do more or less than it claims to do. To validate these claims we have the following “tools”:

• Preconditions: Every routine places a certain set of preconditions that have to be met for the routine to execute.
• Postconditions: Every routine does something to the world it runs in. And this is the mechanism we use to validate that the effects of the routine are as promised.
• Class invariants: Basically describes a set of rules that ensure that the object is in a valid state, from the callers perspective.

If a object and its methods adhere to the principles of DBC all callers know:

• What conditions (states of parameters) must be provided for the method to execute.
• That if the preconditions are met the method will execute.
• That the method fill finish. It is something that we take for granted, but the existence of a postcondition ensures that the method will conclude with a positive or negative result.
• If the method finishes successfully you know exactly what you get.
• After the method is done executing the object will be in a valid state.

And if you follow DBC to the point you will find out that the calling routine is responsible for the preconditions of the called routine. That is something that is hart to realize in the .NET world but is still a nice idea.

Non compiled configuration

Sometimes you have the luxury to decide what is valid or what is not, you can say that the user name may not be shorter than 5 characters. But at the same user names may not be longer than 255 characters. Why is that? Because of the maximum capacity of the database column. And this is my point. In my experience 80% of validation constrains are imposed on the system, from databases, business rules,… So the last thing you want  is to have the validation logic compiled into the code. For example:

public class User
{
  [RequiredField(Message= "A user name has to be provided")]
  [StringLengthRange(MinLength = 5, MaxLength = 255, Message = "The user name must be between 5 and 255 characters long")]
  public string UserName { get; set; }

  [RequiredField(ResourceKey = "Account/UserNameErrorMessage")]
  [StringLengthRange(MinLength = 8, MaxLength = 255, Message = "The password must be between 8 and 255 characters long")]
  public string Password { get; set; }
}

Lets say that because of popular demand the user name length is extended from 255 to 500 characters. Now you have to open the source code, make your changes, compile and redeploy it to the customer. Thats a lot of work for a simple task. Not to speak of a nasty side effect.

This implies that not only the validation logic is hardcoded but the error messages to. So what do you do if you want to provide a multi-language application? Any ideas? Well to put is in plain words: because you rely on some auto-magic mechanism to validate your objects and produce the error messages on the front-end you just ran into a major problem!

And for those of you that are thinking to use the build in resource capabilities let me tell you that you can’t. Why?

1. You do not have any clean access to the culture information of the user (the one using the application)
2. You get a compiler error if you use anything except types and static strings in attributes

So what I want is an external uncompiled, we could call it dynamic, way of configuring the logic. The most popular option is an external XML configuration, like with log4net and nHibernate.

What I want is something like the following:

<validators>
  <validator name="UserNameValidator" base_type="System.string">
    <validator ref="StringNullOrEmpty" />
    <validator ref="Regex">
      <regex>^([a-zA-Z0-9]{6,15})$</regex>
    </validator>
  </validator>
  <validator name="PasswordValidator" base_type="System.string">
    <validator ref="StringNullOrEmpty" />
    <validator ref="Regex">
      <regex>^\w*(?=\w*\d)(?=\w*[a-z])(?=\w*[A-Z])\w*$</regex>
    </validator>
  </validator>
</validators>

<object_validation type="Foo.Person, Foo">
  <invariants>
    <member name="UserName" type="System.string">
      <validator ref="UserNameValidator" />
    </member>
    <member name="Password" type="System.string">
      <validator ref="PasswordValidator" />
    </member>
  </invariants>
<preconditions>
<property name="UserName" direction="set">
      <validator ref="UserNameValidator" />
    </property>
    <method name="SetPassword">
<parameter name="password">
        <validator ref="PasswordValidator" />
      </parameter>
    </method>
  </preconditions>
</object_validation>

Not perfect but it’s a start. Defining the validation like this brings some advantages:

1. You do not have to change your code to change your validation logic
2. You can actually reuse validation logic

IOC

Why do we all love and use log4net and hate other frameworks. I think that one reason is that it just works. But the one I want to point out the fact that log4net does not tightly couple with your code! If you want to test your module and ignore the logging you can. And the same is to be expected from the validation. I do not want that my code gets “infected” by a third party framework. I want to put it in a separate part of the application and talk to it when I want and not when the validation things that I should talk to it.

In achieving this goal IOC is more a guideline. If you design your software like it uses a IOC framework you will get exactly the loosely coupled framework you want. And as an added bonus using it with an IOC framework will be a breeze.

It is not my intention to explain the IOC principle here and list all the IOC frameworks out there. So if you are interested in it here is a nice starting point.

DRY

Don’t repeat yourself! Three words that should guide your every key stroke when writing software!

If I am to use a validation framework I want to define all of my validation logic there. ALL OF IT. I do not want to have some additional code somewhere where it could cause trouble later. So if the framework forces me to write a XML configuration I want it to hold all the validation logic!

Basically like with log4net. I define how to log in the XML configuration later I just say that I want to log something and my log messages land where they should.

So if there has to be some validation code written it should be generated out of the XML configuration.

Extendability

There is no framework out there that could cover all the bases. There is not way that your software could handle all that people want it to do. So I want it to be extendabile! I want to validate my custom object with some fancy rule that no one in their right mind would think about. I should be able to make it happen, with minimal effort.

So that is something that is quite important.

Fluent interface

I know that this breaks some earlier requirements. But for sheer usability there is nothing better. And to be honest, as a software developer I know that it is not a hard thing to do. So give me something like

public ValidatorCollection SetUpValidator()
{
  var validators = new ValidatorCollection();

  var stringValidator = new Validator<User>()
                                 .For(u => u.UserName)
                                 .NotNull()
                                 .NotEmpty()
                                 .LongerThan(8)
                                 .ShorterThan(255)
                                 .Maches("^([a-zA-Z0-9]{6,15})$")
                                 .Message("UserName must...");
  // ...

  validators.Add(stirngValidator);

  // ...

  return validators;
}

Breaks my non compiled principle and potentially the DRY principle but is damn easy to use. And I hate it for that. How can something to wrong be so good to use.

This feature is optional but a really, really nice to have.

What now?

Well that is a good question! To be honest I spend quite some time looking at validation frameworks and non of them fulfill all of the points above. So I decided to do something radical.

I will build my own and share it with the world!

I would like to provide something comparable with log4net. Easy to use but immensely powerful! I even spend 5 minutes creating a logo

valy logo

This is still more of a brain child of mine than a clear plan of what I would like to do. So please do leave a comment and tell me what you would like to see. Or even better, join!

You can find the projects homepage here.

As I mentioned earlier this is still in the faze of figuring out what to do so please be gentle.

Thanks for the support up front!

How to: Elevator

After an extended shopping tour you are standing with your full shopping cart at the elevator and just want to get to your car, which is two floors below you. Sou you stand at the elevator and are faced with a extremely complex user interface whit which evil designers expect you too operate the elevator. That is the feeling i get sometimes!

Lets look at this situation as a normal person. You stand in-front of an elevator. There are two buttons on the wall, one with and up arrow and one with an down arrow. Which one to press? My brain goes: I want to get two floors down into the garage, so I should press the down button. Sound logical right? If you want to go down press the down button, if you want to go up press the up button. No it’s not! Because there are people who are in the same situation and press the wrong button. Why is that?

My first suspect was the user interface itself. But there is not much of an UI to criticize. And to be honest I can’t see how to make it simple. So there has to be another cause for the “misunderstanding”. Once in the same situation I asked the person pressing the wrong button why he did so. And his answer really surprised me. He thought that he has to tell the elevator to come down.

That was a surprise. I find this way of thinking quite funny because of the following:

1. Why should the user know the location of the elevator (he has to at least know if the elevator is above or below him)?
2. Why would the manufacturer of the elevator expect the user to know the location of the elevator?

I have no answer to those questions as does the person pressing the wrong button. So to finish this off please stop pressing the wrong button!

And there is something in there for developers to. Regardless of the simplicity of the user interface there will be people that will just not get it.