public static void BulkInsert<T>(string connection, string tableName, IList<T> list)
{
     using (var bulkCopy = new SqlBulkCopy(connection))
     {
          bulkCopy.BatchSize = list.Count;
          bulkCopy.DestinationTableName = tableName;

          var table = new DataTable();
          var props = TypeDescriptor.GetProperties(typeof(T))
                                     //Dirty hack to make sure we only have system data types 
                                     //i.e. filter out the relationships/collections
                                     .Cast<PropertyDescriptor>()
                                     .Where(propertyInfo => propertyInfo.PropertyType.Namespace.Equals("System"))
                                     .ToArray();
              
          foreach (var propertyInfo in props)
          {             
               bulkCopy.ColumnMappings.Add(propertyInfo.Name, propertyInfo.Name);
               table.Columns.Add(propertyInfo.Name, Nullable.GetUnderlyingType(propertyInfo.PropertyType) ?? propertyInfo.PropertyType);
          }

          var values = new object[props.Length];
          foreach (var item in list)
          {
               for (var i = 0; i < values.Length; i++)
               {
                    values[i] = props[i].GetValue(item);
               }

               table.Rows.Add(values);
          }

          bulkCopy.WriteToServer(table);
     }
}

This works off just a basic list of items which property names match the table column names. Given that most POCO based ORM’s generally match the schema exactly, it works great with EF code first objects.

To use I just build up a list of objects, pick the connection string off the DbContext and then call BulkInsert to save to the DB. Note that in this case I am just adding items to a List<T>, not the EF DbSet<T>.

var imports = new List<Product>();
//Load up the imports

//Pass in cnx, tablename, and list of imports
BulkInsert(context.Database.Connection.ConnectionString, "Products", imports);

public interface IPresenter
{
    void Start(dynamic startupData);
}

public interface ISpecificPresenter : IPresenter
{}

public class SpecificPresenter : ISpecificPresenter
{
    public void Start(dynamic startupData)
    {
        // ...
    }
}

Here we have an interface called IPresenter with a single method on it named Start. Notice that the Start method has a single parameter which is defined as dynamic. We also have another interface called ISpecificPresenter that inherits from IPresenter. Finally we have a concrete class that implements the ISpecificPresenter interface. So far, so good.

Next we have a class called Activator that we use to kick-off a particular presenter.

public class Activator
{
    public void Start<TPresenter>(dynamic startupData)
        where TPresenter : IPresenter
    {
        var presenter = ObjectFactory.GetInstance<TPresenter>();
        presenter.Start(startupData);
    }
}

The Activator class has a generic Start method with a parameter named startupData that is also dynamic. Here we simply get an instance of a requested presenter from StructureMap and call its Start method. This is how to call the Start method of the Activator class :

var activator = new Activator();
activator.Start<ISpecificPresenter>(new{});

When we run this code, we get the following exception:

Microsoft.CSharp.RuntimeBinder.RuntimeBinderException: ‘ISpecificPresenter’ does not contain a definition for ‘Start’.

This had me stumped for a while until I added a cast from ISpecificPresenter to IPresenter in the Start method of the Activator class.

public class Activator
{
    public void Start<TPresenter>(dynamic startupData)
        where TPresenter : IPresenter
    {
        var presenter = (IPresenter)ObjectFactory.GetInstance<TPresenter>();
        presenter.Start(startupData);
    }
}

Now everything works as expected. But I’m not entirely sure why this isn’t behaving as I expected. I guess it has something to do with the fact that the Start method is defined on the IPresenter interface and not on the ISpecificPresenter interface.

Although I very much like the flexibility that dynamic objects bring to the C# language, I’m also starting to think that it might not be such a good idea to bring dynamic concepts to a statically typed language. Running into these kind of issues and limitations reinforces this growing opinion.

I would much appreciate it if anyone could enlighten me with a good explanation.

Until next time.

I really learned a lot from reading the first edition of C# in Depth, so I was very glad that I finally found some time to make my way through the second edition. The content on C# 2.0 and 3.0 was only slightly revised compared to the first edition. Never change a winning combination .

But the final part of the book was the one that most interested me. This part discusses the features provided by the C# 4.0 compiler like optional parameters, named parameters, covariance/contravariance and last but not least, the dynamic keyword that got it’s very own chapter. The last chapter for this final part of the book is completely devoted to Code Contracts, which is not a language feature. I personally don’t like the way that Code Contracts are currently implemented by the .NET framework. I do hope that these concepts are going to be part of the C# language one day, which will be a major improvement regarding enforcing such contracts. Until that day, I think I’m going to stick with my own implementation.  

Anyway, I still think that the title of this book is spot on. If you want to bring your C# skills to the next level, then this book will be you guide. This book is filled with knowledge that only a true C# language expert can deliver. Definitely worth the time and effort.

Happy reading.

I didn’t notice any issues during the initial development of this web service, in fact, I was very pleased with how easy it was to use and integrate this API. Until this very day, I still consider this as one of the nicest and most stable C API’s I’ve ever come across. After I finished most of the features for the web service, I ran a couple of load tests in order to determine whether the respective product could withstand a fair amount of requests and also to detect any glitches that might come up in the interop layer. Nothing major turned up, so we decided to bring this service into production and go on with out merry lives.

Aft first we didn’t receive any complaints. Everything worked out as expected, until earlier this year, we noticed some failures of the application pool for our web service in IIS. The event log showed some random crashes of the CLR (= very bad) with some highly obscure error message. These issues occurred completely random. One day, there were about five to six application pool crashes after which it behaved very stable again, sometimes for months in a row.

After doing some investigation on my part, which also involved stretching my shallow knowledge of WinDbg, I found out that .NET runtime was doing a complete shutdown after an AccessViolationException being thrown. This exception reported the following issue:

Attempted to read or write protected memory. This is often an indication that other memory is corrupt.

The first thing I considered was a memory leak turning up somewhere. It’s unmanaged code after all, right? After reviewing the code that uses the imported native functions, I discovered two potential memory leaks that might come up during some edge case scenarios. So I fixed those, but unfortunately it didn’t resolve the problem.

I tried a couple of other things and also approached the issue from a couple of different angles. I’m not going to bore you with the details here, but it clearly didn’t solve anything. I started to become a bit frustrated with this problem. At some point, I was even convinced that this was all caused by the native library itself and not in our code, which is a classic mistake in most long debugging sessions. The good thing was that I was able to reproduce the problem on my machine, by running the load tests with a particular high load. I noticed that there was also a certain pattern in the number of requests between each crash of the application pool.

Vastly determined to fix this, I decided to read up on some information about P/Invoke and marshaling in .NET. I ended up reading this blog post on P/Invoke and memory related issues. While it didn’t provide a clear solution, reading that blog post certainly guided me in the right direction. I started to turn off feature by feature until I was able to isolate the cause of the crash to a single function call. The native function in question has the following signature:

char* FunctionThatReturnsAString();

As it turned out, I created the following P/Invoke prototype for this native function in C#:

[DllImport("SomeProduct.dll")]
public static extern String FunctionThatReturnsAString();

At first sight (and even after a number of subsequent reviews), there seems to be nothing wrong with the way the char * return value is marshaled to a String. I started reading the excellent documentation for this function again, and it explicitly mentioned that the caller should not cleanup the memory for the return value. The allocated memory for the return value is always cleaned up by the native function itself.

Doing some more research on marshaling strings, I found out that in case the native function does its own cleanup, an IntPtr must be returned by the C# prototype declaration instead of a String.

Most c-style strings returned by native functions must be cleaned up by the calling code. For this common scenario, when the return value is marshaled to a String, the interop marshaler assumes that it has to free the unmanaged memory returned by the function. In our case, this actually means that the interop marshaler tried to cleanup memory that at some point was already freed up by the native function or vice versa.  

So I changed the return value for the P/Invoke prototype declaration to an IntPtr. This way, the interop marshaler does not automatically free the memory that is referenced by the IntPtr.

[DllImport("SomeProduct.dll")]
public static extern IntPtr FunctionThatReturnsAString();

Marshaling the data referenced by the IntPtr to a string is quite easy. This can be done using the Marshal.PtrToStringAuto method.

The lesson I learned here is that we need to watch out for these kind of issues when using interop with unmanaged code. On the surface everything seems to work out just fine, but one can still run into some nasty issues afterwards. Carefully considering how to correctly marshal data from and to unmanaged code is an essential technique and sometimes feels like a black art that is not suited for the faint of heart, like myself .

A word of caution before I go into how to not have to parse XML!

What I am going to describe is not always going to be the best solution.  It is an easy solution that will cover simple processing of XML files.  For a large XML file, the solutions I am going to suggest might be memory intensive and take too long.

Seems like everyone is doing it

I’ve walked into so many software development shops and seen code to parse XML files.  It seems to be one of those really common things that not enough developers realize can be completely automated.

I have started to wonder if it is self-propagating.  If developers have a tendency to see it being manually parsed in one place, assume that there is not a better way, then propagate that manual parsing to the next place they go.

Why is it so bad?

First of all, it is not an easy task to parse XML.  Even when using an XML parsing library there is a large amount of code that has to be written, especially for a complex XSD.

XML parsing code is also very fragile.  If the structure of an XML file changes, the code will have to be modified, and the modification can have cascading effects.

Manually generated XML parsing code cannot be regenerated if the structure of the XML changes.

Most importantly, any code you have to write runs the risk of introducing bugs and complexity into the system.

It’s so simple you wouldn’t believe it

So, how simple is it to automatically parse XML into objects?

Very simple.  First I am going to give you the basic pattern, then I am going to tell you how to do it in both C# and Java.

Basic pattern:

1. Use a tool to generate an inferred XSD from your XML file.  (You can skip this step if you already have an XSD file.)
2. Use a code generation tool to generate your classes automatically from the XSD file.
3. In your code, deserialize your XML file into an object tree using the framework you generated the classes from.

If you are doing something more complex than this, without a really good reason, you are doing it wrong!

Learning how to do this in your language of choice is a very important tool to put into your tool bag.  There are many times that I have run into the need to parse XML files, where I have saved many hours of development time, by knowing how to automatically deserialize my XML files into objects.

There are two main ways in which XML serialization frameworks work.

1. Serializers that auto-generate the classes from the XSD files.
2. Serializers that use annotations or attributes on classes.

Using a serializer that auto-generates the classes from an XSD is the easiest to use and can work in most cases.  If you need more control over the generation of the XML, you might want to use an attribute or annotation based framework.

One of the biggest barriers in getting started with an XML framework is knowing what to use and how to use it.  I am going to cover 3 options that will get you going for C#, Java SE, and Java Android development.

C# (XSD.exe)

XML serialization is so easy in C# because it is built right into the .NET framework.

The only real piece of magic you need to know is the XSD.exe tool which is installed with Visual Studio.  This one tool can be run to infer an XSD from your XML file and then again to take that XSD and produce fully serializable / deserializable classes.

If you have an XML file named myFile.xml, you can simply go to the Visual Studio command prompt and type:

xsd myFile.xml

Which will produce a myFile.xsd.

Then type

xsd myFile.xsd /c

This will generate a set of classes that you can add to your project, and then you can deserialize an xml file with this simple code:

   1: XmlSerializer serializer = 

   2: new XmlSerializer(typeof(MyFile));

   3:  

   4: Stream reader = new FileStream("myFile.xml",FileMode.Open);

   5:  

   6: MyFile myFile = (MyFile) serializer.Deserialize(reader);

Java (JAXB)

The steps are slightly more complicated with JAXB, but it is still fairly easy.

First we have to generate an XSD file from an XML file.  JAXB doesn’t do this itself as far as I know, but there is another tool we can use called Trang.

First step, download Trang, then run it like so:

java –jar trang.jar –I xml –O xsd myFile.xml myFile.xsd

You can also use the XSD.exe tool from Visual Studio if you have it installed or download it.  There are a few other tools out there as well.

Once you have the XSD file, or if you already had one you had written, you need to generate Java classes using JAXB’s tool like so:

xjc –p my.package.name myFile.xsd –d myDirectory

Running this command will produce Java files that represent the elements in your XML document.

Finally, to create your objects you can use the JAXB unmarshaller.

   1: JAXBContext jc = JAXBContext.newInstance("my.package.name");

   2: Unmarshaller unmarshaller = jc.createUnmarshaller();

   3: MyFile myFile = (MyFile) unmarshaller.unmarshal(new File( "myFile.xml"));

Not as simple as the C# example, but really quite simple.  I’ve omitted the steps like downloading JAXB and adding it to your class path, but you can see that the process really is not very painful at all.

JAXB also provides some options for customizing the serialization and deserialization.

Android (Simple XML)

You can’t use JAXB with Android.  It seems like because of the Dalvik VM, the reflection part of JAXB doesn’t work.

I found a pretty good and small XML framework that I am using in my Android app that seems to do the trick nicely.  You have to annotate your classes and create them by hand, but it is very simple and straightforward to do so.

The tool is called “Simple XML.”

You can find lots of examples on the “tutorial” tab on the web page.

Basically, you download Simple XML, add the jars to you class path, and create class files with some annotations to specify how to deserialize or serialize your XML.

Here is a small example of an annotated class, from the Simple XML website.

   1: @Root

   2: public class Example {

   3:  

   4:    @Element

   5:    private String text;

   6:  

   7:    @Attribute

   8:    private int index;

   9:  

  10:    public Example() {

  11:       super();

  12:    }  

  13:  

  14:    public Example(String text, int index) {

  15:       this.text = text;

  16:       this.index = index;

  17:    }

  18:  

  19:    public String getMessage() {

  20:       return text;

  21:    }

  22:  

  23:    public int getId() {

  24:       return index;

  25:    }

  26: }

To deserialize this xml you just use the following code.

   1: Serializer serializer = new Persister();

   2: File source = new File("example.xml");

   3:  

   4: Example example = serializer.read(Example.class, source)

Very simple and straightforward.  The only downside is generating the Java class files yourself, but that isn’t really very hard to do using the annotations.

No excuses

So there you have it, XML serialization frameworks abound to make your life easier when dealing with XML.  For most simple cases you should never handwrite XML parsing code, even when using a library to help you do it.

Now that I’ve shown you how easy it is, there really are no excuses!

As always, you can subscribe to this RSS feed to follow my posts on elegant code.  Feel free to check out my main personal blog at http://simpleprogrammer.com, which has a wider range of posts, updated 2-3 times a week.  Also, you can follow me on twitter here.

var subject = new Subject();
var doSomething = (Func<String, String>)
    Delegate.CreateDelegate(typeof(Func<String, String>), subject, "DoSomething");
Console.WriteLine(doSomething("Hello Freggles"));

Here we’re simply able to cast the result to the requested delegate type. But what if a generic method must be invoked for which the type parameters can vary at runtime? You can still use the CreateDelegate method, but you can’t cast the result to a strongly typed delegate type. This means that in order to invoke the created delegate, the DynamicInvoke method must be called on the returned Delegate object. This has the nasty side effect that when the original method being called throws an exception, the DynamicInvoke method wraps the original exception in a TargetInvocationException.  

So in order to find a better way and also exercise my Expressions-fu, I tried to come up with a CreateDelegate<T> extension method that can be used to a create a strongly typed delegate for a MethodInfo object.

Suppose we have to dynamically invoke a method with the following signature:

private void Map<TDomainEvent, TEvent>(TDomainEvent domainEvent, TEvent @event)
    where TDomainEvent : IDomainEvent
    where TEvent : IEvent
{
    ...
}

Given an instance of IDomainEvent and IEvent, using the CreateDelegate<T> extension method that I’m about to show, we can dynamically invoke this method using the following code:

var action = GetType()
    .GetMethod("Map", methodBindings)
    .MakeGenericMethod(domainEvent.GetType(), @event.GetType())
    .CreateDelegate<Action<IDomainEvent, IEvent>>(this);

action(domainEvent, @event);

Here we determine a specific MethodInfo object for the Map method using the types of the event objects we have. Now here’s the code for the strongly typed CreateDelegate extension method.

public static class MethodInfoExtensions
{
    public static TDelegate CreateDelegate<TDelegate>(this MethodInfo method,
                                                      Object instance)
        where TDelegate : class
    {
        return CreateCachedDelegate<TDelegate>(method,
            (typeArguments, parameterExpressions) =>
            {
                Expression<Func<Object>> instanceExpression = () => instance;
                return Expression.Call(Expression.Convert(instanceExpression.Body,
                                                          instance.GetType()),
                                       method.Name,
                                       typeArguments,
                                       ProvideStrongArgumentsFor(method,
                                                                 parameterExpressions));
            });
    }

    public static TDelegate CreateDelegate<TDelegate>(this MethodInfo method)
        where TDelegate : class
    {
        return CreateCachedDelegate<TDelegate>(method,
            (typeArguments, parameterExpressions) =>
                Expression.Call(method.DeclaringType, method.Name, typeArguments,
                                ProvideStrongArgumentsFor(method, parameterExpressions)));
    }

    private static TDelegate CreateCachedDelegate<TDelegate>(MethodBase method,
        Func<Type[], ParameterExpression[], MethodCallExpression> getCallExpression)
        where TDelegate : class
    {
        var @delegate = GetFromCache<TDelegate>();
        if(null == @delegate)
        {
            @delegate = CreateDelegate<TDelegate>(method, getCallExpression);
            StoreInCache(@delegate);
        }

        return @delegate;
    }

    private static TDelegate GetFromCache<TDelegate>()
    {
        Object delegateObj;
        if(_delegateCache.TryGetValue(typeof(TDelegate), out delegateObj))
            return (TDelegate)delegateObj;

        return default(TDelegate);
    }

    private static void StoreInCache<TDelegate>(TDelegate @delegate)
    {
        _delegateCache.TryAdd(typeof(TDelegate), @delegate);
    }

    private static TDelegate CreateDelegate<TDelegate>(MethodBase method,
        Func<Type[], ParameterExpression[], MethodCallExpression> getCallExpression)
    {
        var parameterExpressions = ExtractParameterExpressionsFrom<TDelegate>();
        CheckParameterCountsAreEqual(parameterExpressions, method.GetParameters());

        var call = getCallExpression(GetTypeArgumentsFor(method), parameterExpressions);

        var lambda = Expression.Lambda<TDelegate>(call, parameterExpressions);
        return lambda.Compile();
    }

    private static ParameterExpression[] ExtractParameterExpressionsFrom<TDelegate>()
    {
        return typeof(TDelegate)
            .GetMethod("Invoke")
            .GetParameters()
            .ToParameterExpressions()
            .ToArray();
    }

    private static void CheckParameterCountsAreEqual(
        IEnumerable<ParameterExpression> delegateParameters,
        IEnumerable<ParameterInfo> methodParameters)
    {
        if(delegateParameters.Count() != methodParameters.Count())
            throw new InvalidOperationException(
                "The number of parameters of the requested delegate does not match " +
                "the number parameters of the specified method.");
    }

    private static Type[] GetTypeArgumentsFor(MethodBase method)
    {
        var typeArguments = method.GetGenericArguments();
        return (typeArguments.Length > 0) ? typeArguments : null;
    }

    private static Expression[] ProvideStrongArgumentsFor(
        MethodInfo method, ParameterExpression[] parameterExpressions)
    {
        return method.GetParameters()
            .Select((parameter, index) =>
                Expression.Convert(parameterExpressions[index],
                                   parameter.ParameterType))
            .ToArray();
    }

    private static readonly ConcurrentDictionary<Type, Object> _delegateCache =
        new ConcurrentDictionary<Type, Object>();
}

I actually provided two CreateDelegate methods here, one for instance methods (the first one) and one for static methods ( the second one). The created delegates are cached in a dictionary because the call of lambda.Compile() seems to be quite expensive.

Now I have to warn you that, based on first preliminary measurements, this implementation probably isn’t going to outperform  Delegate.CreateDelegate(). In fact, if you’re interested have a look at this approach first as it seems much faster. I added some spike code to the Elegant Code repository for those who fancy to take a look.  

I always considered Java to be some kind of parallel universe compared to .NET where a lot of interesting lessons can be learned. I never did any serious Java development throughout my professional career, but I like to follow up on the trends in the Java community. Although the Java community suffers from some of the same diseases as the .NET community, the wide-spread acceptance of open-source and the adoption of new, fascinating languages on top of the JVM is an interesting evolution that I feel is lacking in the .NET world. Although the CLR/DLR is probably better designed to host a wider diversity of programming languages than the JVM, the rise of programming languages like Scala, Clojure, Groovy and others is more sparse in the Java universe. Some of the most useful open-source projects in .NET today  initially started out by porting the code of established Java libraries, like NUnit, NHibernate and Spring.NET, etc. …. Anyway, we’re wandering off.

Did you ever need to interoperate with a Java library while developing .NET applications? I have to admit, it doesn’t come up very often but when it does (especially when using IBM products ), IKVM.NET might save you from a whole lot of trouble.

With IKVM.NET its possible to use Java API’s from a .NET application or even to use the Java language to develop .NET applications. Let me show you a quick example.

Say for example that you’re done with the DateTime class in .NET and you need a library that gives you more power in dealing with dates and time in your .NET applications. You do a little searching on the web and there it is, a full blown API like Joda Time (I’m well aware that honorable Jon Skeet has ported this framework to .NET already, but bear with me).

All we have to do to start using Joda Time in a .NET application is to download joda-time.jar and feed it to the ikvmc.exe command-line tool that comes with the binaries of IKVM.NET. Out comes a full blown .NET assembly by executing the following command:

ikvmc -target:library joda-time-1.6.jar

There are a whole slew of other options that you can specify here, like signing the resulting assembly (who still does that, really), specifying the assembly version, etc. …

This is how the generated assembly looks like in Reflector.

The following block of code is small utility that I developed to deal with the time zone arithmetic for the Europe Virtual ALT.NET.

using System;
using System.Windows.Forms;
using org.joda.time;
using org.joda.time.format;
using DateTime = org.joda.time.DateTime;
using TimeZone = java.util.TimeZone;

public partial class Main : Form
{
    private const String London = "Europe/London";
    private const String Brussels = "Europe/Brussels";
    private const String EST = "EST";
    private const String MST = "MST";
    private const String PST = "PST";

    public Main()
    {
        InitializeComponent();
        DateTimeTextBox.Text = CurrentDateAndTime();
    }

    private void ConvertButton_Click(Object sender, EventArgs e)
    {
        var dateTime = new DateTime(DateTimeTextBox.Text, DateTimeZone.UTC);

        var london = ConvertToTimeZone(London, dateTime);
        var brussels = ConvertToTimeZone(Brussels, dateTime);
        var est = ConvertToTimeZone(EST, dateTime);
        var mst = ConvertToTimeZone(MST, dateTime);
        var pst = ConvertToTimeZone(PST, dateTime);

        var formatter = BuildDateTimeFormatter();

        ResultTextBox.Text = String.Format(
            "{0} UK, {1} Brussels, {2} EST, {3} MST and {4} PST.",
            london.toString(formatter),
            brussels.toString(formatter),
            est.toString(formatter),
            mst.toString(formatter),
            pst.toString(formatter));
    }

    private static String CurrentDateAndTime()
    {
        return new DateTime(DateTimeZone.UTC).ToString();
    }

    private static DateTime ConvertToTimeZone(String timeZone, DateTime dateTime)
    {
        var targetTimeZone = DateTimeZone
            .forTimeZone(TimeZone.getTimeZone(timeZone));
        return dateTime.toDateTime(targetTimeZone);
    }

    private static DateTimeFormatter BuildDateTimeFormatter()
    {
        return new DateTimeFormatterBuilder()
            .appendHourOfHalfday(2)
            .appendLiteral(":")
            .appendMinuteOfHour(2)
            .appendLiteral(" ")
            .appendHalfdayOfDayText()
            .toFormatter();
    }
}

The distribution of IKVM.NET also comes with .NET implementation of a whole slew of Java class libraries that you can directly use in a .NET application whenever needed.

But remember, as with all things that seem too good to be true, there are a couple of major downsides as well. The one that you run into fairly quickly is generics. I tried generating a .NET assembly from Make It Easy the other day and I noticed that some of the types in the resulting assembly where plain classes while they were defined as generics in the original JAR file. The explanation that I found was that Java checks generics only at compile time and not at runtime. In .NET generics are provided at runtime. If the generics from Java would convert to .NET, then every Java compiler warning would produce a runtime error. All the old code would not run. There is many old code in the Java VM itself.

The IKVM.NET blog is a great resource for some of the other interoperability issues you might experience. Maybe this will come in handy someday, who knows?

Till next time.

Most of us write code for the purpose of achieving a goal.  If we practice writing elegant code, we are conscious of making that code as readable and terse as possible.

Seldom do we think about the use of our code from an API standpoint.

There is a subtle difference between designing your code in a way that will make it easier for someone else to maintain, and designing your code in a way that will make it easier for someone else to use.

Intellisenselessness

How often are you working against some API and you type a method name you want to use only to have intellisense present you with 5 overloads for the method all with several different parameters choices?

Which one do you use?  It is hard to be sure, you end up having to read through the long lists of parameters to figure out what method you should call and what parameters you should pass it.

Wouldn’t it be better if you were presented with what the method does in the method name rather than guessing what it does in the parameter list?  Something like this?

Perspective

From the perspective of the person writing the Login method(s), overloads probably seem like the most efficient and correct way to implement the multiple ways the method can be called.

From the perspective of the person using the Login method(s), additional methods are much preferred, because they are easier to understand and know what you are looking for.

Try to think from the perspective of someone using your code when writing your code.

Extract boolean parameter to two methods

I want to take a look at a very specific example that can be of great benefit to the readability and use of your code.

Take a look at this code below.

   1: public void Login()

   2: {

   3: }

   4:  

   5: public void Login(bool rememberMe)

   6: {

   7: }

Seems like a fine overload of a Login method.  I have written code just like this, you probably have also. 

Unfortunately, by adding this overload, we have added some complexity to our API, because now the user of that code has to see that there is an additional overload that take a bool parameter called rememberMe.

Consider this longer alternative.

   1: public void LoginRememberMe()

   2: {

   3: }

   4:  

   5: public void LoginDoNotRememberMe()

   6: {

   7: }

Instead of overloading Login and making the user have to decide which overload to call and pass in a parameter, we have elected to create two differently named methods which take 0 parameters and clearly state what they are going to do.

I’m not saying you should never write overloads, but anytime you see an overload in your code base, you should stop and think if it would be more clear to make that overloaded method into two different methods that can eliminate one or more of the parameters.

Any time you are restricting the number of choices someone using your code has to make, you are making that code simpler to use.

If you don’t believe me, consider why the iPhone has only one button.

As always, you can subscribe to this RSS feed to follow my posts on elegant code.  Feel free to check out my main personal blog at http://simpleprogrammer.com, which has a wider range of posts, updated 2-3 times a week.  Also, you can follow me on twitter here.

The enumeration is such a simple concept, yet it yields such a high return in both readability and usability of your code.

The enum is able to eliminate the need for XML style comments for a parameter to a method, and prevent the passing of null in one fell swoop.

• Enumerations make the set of choices for a parameter finite and self-describing.
• Enumerations which are parameters can never be set to null.

Explicit documentation becomes self-documentation

Let’s look at an example, so I can show you what I am talking about:

/// <summary>
/// Causes pacman to eat the specified fruit.
/// </summary>
/// <param name="fruit">A fruit which must either be an apple, banana, orange, or

/// cherries.</param>
public void Eat(string fruit)
{
    switch(fruit)
    {
        case "apple":
            Console.WriteLine("Ate an apple");
            break;
        case "banana":
            Console.WriteLine("I love bananas");
            break;
        case "orange":
            Console.WriteLine("A color and a fruit");
            break;
        case "cherries":
            Console.WriteLine("This one is plural");
            break;
        default:
            break;
    }
}

You can see here that we need some comment to tell the user of the method what can be passed into the fruit parameter.

We have to handle the default case, in case someone is able to pass in something we didn’t expect.

A simple typo in calling the method or in our method, could result in a difficult to find bug.

Someone can call this method with null like so:

// passing in null is allowed, strings can be null, objects can always be null.
Eat(null);

Now take a look at the example that uses an enumeration for fruits.

public void Eat(Fruits fruit)
{
    switch (fruit)
    {
        case Fruits.Apple:
            Console.WriteLine("Ate an apple");
            break;
        case Fruits.Banana:
            Console.WriteLine("I love bananas");
            break;
        case Fruits.Orange:
            Console.WriteLine("A color and a fruit");
            break;
        case Fruits.Cherries:
            Console.WriteLine("This one is plural");
            break;
    }
}

Do we really need the XML comment anymore?  When you try to call Eat() you will immediately see that it requires a Fruit and when you type “Fruit.” you will get:

Pretty self-explanatory.

Consider what happens when I try to pass null into the method.

You cannot do it.  No matter how hard you try.

Side note: before the comments start coming in.  The example above is using a switch statement so that it can be simple for demonstration.  In real code you would want to do something smarter here like use a Dictionary<Fruits, string> and replace the switch.

The power of limiting choices

It is a funny kind of a seeming contradiction that limiting the amount of choices increases the effectiveness of something.

The real power of enumerations to make your code more elegant lies in this contradiction.  By constraining the choices of what can be passed into a method, it becomes possible to list those choices out.  Which allows intellisense to display the choices for you.  You are forcing the IDE to document your code automatically.

Options that are self-discoverable are always going to be easier to use and understand, because they don’t require the mind to parse a human sentence and translate it into code.

Limiting choices protects your code in many other ways.  You prevent typos on either end because the compiler will now tell you if you have typed one of the choices wrong.

Testing becomes simpler, because the choices are finite.  Edge conditions and testing invalid input don’t apply to methods that take enumerations.  All input possibilities are known.

When to use enumerations

It is more often than you would think.  Let me show you an example where many people might not notice they could use an enum:

public void StartGame(int numberOfPlayers);

Many programmers would look at this code and not even think about using an enumeration here.  The number of players feels like an integer.

Every time you are writing a method and declaring the parameters, you should be asking yourself “How can I constrain the choices of what can be passed in?”

In this case, it is very simple.  How many players does the game allow?  There might even be a constant MAX_PLAYERS = 4.

We can very easily convert this code to use a simple enum and constrain the choices.

public void StartGame(PlayerCountSelection numberOfPlayers);

This small change may not seem like much, but it is going to immediately eliminate the need for writing unit tests to check for invalid player amounts being passed in, and it is going to prevent another programmer using this method from having to look in the documentation to find out the valid ranges of the int.

It is the culmination of limiting choices throughout your code that produces a net effect of reducing the complexity of the system.  It is the same with most of the best practices I suggest on this blog.

So when should you use enumerations?  Any time you can.  Any time you have the opportunity to constrain input choices, do it.

Combine them with maps and function pointers for the ultimate combo!

As always, you can subscribe to this RSS feed to follow my posts on elegant code.  Feel free to check out my main personal blog at http://simpleprogrammer.com, which has a wider range of posts, updated 2-3 times a week.  Also, you can follow me on twitter here.

What do you do if “null” is passed in?

My answer may turn out to be a bit of a surprise.

Nothing, I don’t handle nulls in code that I control the use of.

“What?  What?” you say.  “You don’t handle null?  What kind of heresy is that?”  It is the kind of heresy that helps produce elegant code and I will show you why.

How well do you handle null right now?

Would you say that in most of the code you write you properly check all arguments for null?

Or, do you like most developers, handle null in certain cases when you happen to think about it, or after the application dumps a “null pointer exception” stack trace?

Be honest, look at your code if you have to.

The problem is “d00d ur d0ing it r0ng!”

Unless you are some kind of anal retentive perfectionist, you are probably not handling null in every single method call.  That means there are huge potential bugs in the code that you are writing which will throw null pointer exceptions.  That is bad, I agree.

So, if you are not handling it correctly right now, then what can you do to fix that?

Avoiding null in the code you “own”

You can’t control external libraries.  And you can’t control how people will use your code, but you can control the code you write and you can, to a degree, control the code your shop writes.

The better strategy is to never pass null in the first place.

You can either focus your efforts on:

• Checking for null
• Not ever passing null

The more elegant solution is to focus on never passing null.  By doing this you will end up writing less code and avoid decisions about how to handle null inside of a method that doesn’t have enough context to decide what to do.

Let’s look at an example:

public string TransmographyThreeStrings(string first, string second, string third)
{
     if(string.isNull(first) || string.isNull(second) || string.isNull(third))
    {
           // hmm, I donno, what should I do?  Should I throw an exception?
           // should I return an empty string?
           // what if the first string wasn't null, can we still do something meaningful?
           // how will the caller of the method know what I will do?
    }

}

You can see there that we are checking each parameter for null.  The problem is we don’t know what we should do.  We have lots of options, but none of them are obvious.

How much better is it to make sure that we never pass null into methods, rather than write this kind of code in every method?

What about accidentally passing in null?

Many of you are probably thinking at this point that the main way null gets passed into a method is because someone calls a method without knowing that it contains a null value.

TransmographyThreeStrings("Hello", "World", mysteryObject.Text);

Perhaps mysteryObject.Text is null.  You wouldn’t even know it.

Ah, but you can.  Or you can prevent it at least.  Somewhere mysteryObject gets created.  When it gets created its values either get initialized or not.  You can prevent any of its values from being null, several ways:

• Always initialize variables when they are declared.
• Use a builder pattern to ensure that objects are always fully constructed before being created.
• Use properties to provide default values or lazy initialize.
• Make your objects immutable as much as possible.

The practices that prevent null from accidentally being passed in make your code much more elegant than repeating if blah == null code all over the place.

In general, you should always strive to eliminate the passing of null rather than checking for null.  By doing so you reduce extra lines of code in each method, and are forced to use better design practices.

Exceptions

Yes, there are times when you need to check for null.  If you are writing a library that external developers will use, then you will probably want to check for null in all of your methods that are exposed as part of the API.  (On your internal methods, you don’t need to since you have already cleansed the input.)

Also, if your code is being used as a callback to some API and you don’t know if it can ever pass null into your code, you probably should check for null.

A bad excuse is that other developers may pass null to your method. It is much better as a software shop to put the onus of not passing null on the caller of any method rather than putting it on the writer of the method being called.

You will also reduce your exception handling code, because you will have less exceptions for invalid parameters.

As always, you can subscribe to this RSS feed to follow my posts on elegant code.  Feel free to check out my main personal blog at http://simpleprogrammer.com, which has a wider range of posts, updated 2-3 times a week.  Also, you can follow me on twitter here.