One of the advantages of doing test driven development & unit testing is having the unit tests as documentation of the code. When you read this in the unit testing / TDD books, it is hard to imagine how this would be of use in practice.

As one of my favorite bloggers, Jeremy Miller, already writes, the NHibernate source is a really good example of using the tests as documentation. I think this is especially the case when developing frameworks or libraries. Because the code will always be used by developers, the best way for a developer to see how the code should be used is by looking at the unit tests as an example.

I experienced this myself a couple of days ago with the same code that Jeremy mentions. I also used the NHibernate EnumStringType to use an enum type that is represented in the database as a string column. This works great, but when I wanted to use the enum type in a HQL query, it didn’t work the way I had expected:

            IQuery q = s.CreateQuery("from Order as order where order.State =:orderState");
            q.SetEnum("orderState", OrderState.Open);
            IList results = q.List();

The code above gave me a vague oracle exception. So i needed to figure out how to pass the parameter to the HQL query. I fired up the NHIbernate source to open the unit test for the EnumStringType:

I then opened the test, which gave me the right code:

        [Test]
        public void ReadFromQuery()
        {
            ISession s = OpenSession();

            IQuery q = s.CreateQuery("from EnumStringClass as esc where esc.EnumValue=:enumValue");
            q.SetParameter("enumValue", SampleEnum.On, new SampleEnumType());
            q.SetEnum("enumValue", SampleEnum.On);
            IList results = q.List();

            Assert.AreEqual(1, results.Count, "only 1 was 'On'");

            q.SetParameter("enumValue", SampleEnum.Off, new SampleEnumType());
            results = q.List();

            Assert.AreEqual(0, results.Count, "should not be any in the 'Off' status");

            s.Close();

            // it will also be possible to query based on a string value
            // since that is what is in the db
            s = OpenSession();

            q = s.CreateQuery("from EnumStringClass as esc where esc.EnumValue=:stringValue");
            q.SetString("stringValue", "On");
            results = q.List();

            Assert.AreEqual(1, results.Count, "only 1 was 'On' string");

            q.SetString("stringValue", "Off");
            results = q.List();

            Assert.AreEqual(0, results.Count, "should not be any in the 'Off' string");

            s.Close();
        }

As Jeremy also mentions, the NHibernate documentation isn’t as complete as we would have hoped, the EnumStringType isn’t documented for example. But as the example above illustrates, these unit tests can be really helpful as technical documentation, especially when it concerns frameworks and libraries.

I’m becoming a big fan of test-driven development, yes, I actually write my tests before writing my code. It is a different mind-set and you really have to just do it a lot before really adopting to this mind-set.

When unittesting a class you often need mock objects to test interaction with other classes. Until shortly, I used NMock to mock those other classes. I really like NMock, it has a nice API, which adheres to Martin Fowlers’ Fluent Interface. But there has not been a lot of activity around the NMock project last year, it looks like development has been stopped. I also didn’t really like the fact that you had to pass expected calls as string values, like: Expect.On(myMock).Method(“MyMethod”). I didn’t like this, because you can’t make use of the compiler to check if the method exists and you can’t use tools like ReSharper to implement the method, when doing test-driven development.

Lately another mocking framework’s name turns up a lot, namely Rhino Mocks. It has been created by the same guy who did the NHibernate Query Analyzer. Anyways, I’ve been trying out Rhino Mock and it supports the same fluent interface as NMock. But the best thing is, that it supports setting expectations to real method names, like: Expect.On(myMock).Call(myMock.MyMethod). There also is a lot of activity around the project and using the mailing list will get you help frighteningly fast. Check it out.

If you are a NHibernate user and writing HQL queries like me, you definitely need to check out Ayende’s NHibernate Query Analyzer. With this tool, you can load up your NHibernate mapping files, your business model and a NHibernate configuration file, after which you can query the objects in the business model and see what sql is generated under water. It is also possible to execute the queries, so this tool is excellent for (performance) tuning your HQL queries.

Be sure to check out the flash demo, download the tool here.

Lately I have been working with a lot of source code that was developed by other developers and although some of it was of good quality, other code was of… less quality. As a developer I’m always trying to improve the work I deliver, that’s why I read lots of books and blog posts. Because of reading books like Code Complete, The Pragmatic Programmer, Coder to Developer, etc., I think I have grown an understanding about what good code, read maintainable code, looks like. Developing an application just to implement some functionality is one thing, but doing this in a way in which the application being developed is also easy to maintain in the future, is a whole other thing. When code is written without keeping maintainability in mind, the code really gets hard to… maintain. It will be hard to find the implementation of specific functionality, hard to determine the impact of a modification, etcetera. This can even result in code that no developer dares to touch anymore, afraid of causing a domino effect that will break most of the system’s functionality.

For these reasons, every serious developer should be familiar with writing maintainable code. J. Miller has written some excellent posts, which capture the most important aspects about writing maintainable code, without getting too theoretical. His first post is an introduction on writing maintainable code and his second post is a follow-up on orthogonal code.