markhneedham/blog huggingface dataset:
Pair Programming: API exploration
Date: 2009-10-11 14:49:21

A colleague and I were working on some code a couple of weeks ago which mostly revolved around investigating the C# reflection API to work out which methods we needed to use.

My colleague was driving while we were doing this and our progress seemed very much based on intuition about the API rather than being gradual.

In fact it was quite similar to one of the situations in which Uncle Bob suggests http://blog.objectmentor.com/articles/2009/10/08/tdd-triage[TDD doesn't work so well]:

____
\... I need the freedom to fiddle around with the formatting and the structure until everything is just the way I want it. Trying to do that fiddling with TDD is futile. Once I have the page the way I like it, then I'll write some tests that make sure the templates work as written.
____

My colleague was fiddling around with the code trying to work out what combination of methods we needed to call and I was struggling a bit to get involved through no fault of my colleague.

He was http://www.markhneedham.com/blog/2009/08/24/pair-programming-keeping-both-people-engaged/[describing what he was doing] but for a lot of the time what we tried didn't work and then suddenly it worked.

It all seemed a bit magical to me!

At this stage we decided to refactor the code and thought that it would might be useful for me to do that refactoring so that I could explain my understanding of the code my colleague had just written and see if I had followed what he'd been doing.

I was able to extract out methods correctly most of the time but there were a couple of places where I hadn't quite understood what was happening so this approach allowed my colleague to explain it to me.

My initial thinking when we started doing this coding was that perhaps it wasn't suitable for pairing because it's quite exploratory but it seemed to work out reasonably well and my understanding of reflection is now slightly better thanks to my colleague's explanations.
Coding: Consistency when invariant checking
Date: 2009-10-29 23:06:35

I wrote a while ago about http://www.markhneedham.com/blog/2009/02/14/coding-assertions-in-constructors/[reading the ASP.NET MVC source code and noticing that it makes use of code inside its constructors to ensure that null values can't be passed in] and while I'm still not convinced this is the way to go I think if we do take this approach then we need to ensure we do so consistently.

Something which happens quite often is that you'll come across code which makes use of defensive programming in one of its constructors like so:

[source,java]
----

public class SomeObject
{
	public SomeObject(Dependency1 valueOne, Dependency2 valueTwo)
	{
		AssertThat.isNotNull(valueOne);
		AssertThat.isNotNull(valueTwo);
		// and so on
	}
}
----

This is fine in itself but you'll often find another constructor defined close by which looks like this:

[source,java]
----

public class SomeObject
{
	public SomeObject(Dependency1 valueOne, Dependency2 valueTwo)
	{
		this.valueOne = null;
		this.valueTwo = null;
	}
}
----

Depending which constructor you use the outcome is quite different and you probably wouldn't expect the default constructor to allow nulls seeing as the other one prevents you from doing this.

This inconsistency can happen for a variety of reasons.

== Test only constructor

It might be a http://www.markhneedham.com/blog/2009/09/12/tdd-test-only-constructors/[test only constructor] which is not intended to be called in production case. It's much easier to get an object under test if we don't have to supply any parameters.

In that case though we're testing the object constructed in a much different state than it will be when we really use it so the value of this type of testing is questionable.

It's probably best to look why we need that test only constructor and see if we can change the code so that we can avoid that problem.

== An implicit domain concept

Another reason is that the original pre condition of the object might have changed and now it isn't always the case that we need to provide 'Dependency1' and 'Dependency2'.

In this case I think it would make more sense to make that more explicit, perhaps by making use of the http://www.markhneedham.com/blog/2008/08/16/null-handling-strategies/[null object pattern] or by finding another abstraction which doesn't require nulls to be passed around.

Either way we should probably look to ensure that both constructors either ignore nulls or both stop them from being set.

== Didn't realise pre conditions were being checked

Although this one might seem a bit far fetched it's pretty easy for this to be the case if there are different people working on the code base.

Someone might glance at the class, see that it doesn't quite allow them to construct the object the way they want and create another constructor without realising the way the original one was working.

In this case talking more about the way that we're solving this type of problem across the code base should be enough to ensure that we get some kind of consistency.
Treating Javascript as an integration point
Date: 2009-10-17 09:16:12

A couple of weeks ago http://www.markhneedham.com/blog/2009/10/05/my-software-development-journey-year-3-4/[I wrote a post about my software development journey] over the last year and towards the end I described the difficulties we were having in making changes to some C# code while being sure that we hadn't broken javascript functionality that also relied on that code.

We typically have code which looks like this:

[source,csharp]
----

public class SomeController
{
	public ActionResult SomeControllerAction()
	{
		var someModel = new SomeModel { Property1 = "my Property" };

		return new JsonResult { Data = someModel };
	}
}

public class SomeModel
{
	public string Property1 { get; set; }
}
----

We would make use of this type of object in javascript code like so:

[source,javascript]
----

$.getJSON("/SomeController/SomeControllerAction",
        function(data){
			var value = data.Property1;
			// do some cool stuff with that value
		}
);
----

My colleague Raymond Maung recently came up with the idea of writing tests to ensure that the properties we make use of in Javascript exist on the C# objects which we return in JSON calls.

We now have a testing extension method which uses reflection to check that the expected properties are set.

[source,csharp]
----

public static class TestingExtensions
{
        public static void AssertHasProperty(this Type type, string propertyName)
        {
            var property = type.GetProperty(propertyName);
            Assert.IsNotNull(property, "Expected {0} to have property '{1}' but it didn't", type.Name, propertyName);
        }
}
----

[source,csharp]
----

[Test]
public void ShouldEnsurePropertiesRequiredInJavascriptAreSet()
{
	var type = typeof(SomeModel);
	type.AssertHasProperty("Property1");
	// and so on
}
----

It still requires the developer to remember to put a test in if they add a property to the C# model but I think it's working better than having to switch between the javascript and C# files checking that you haven't broken anything.
TDD: Keeping assertions clear
Date: 2009-10-10 11:07:21

Something which I noticed was a problem with the first example test that I provided in my post about http://www.markhneedham.com/blog/2009/10/10/coding-api-readabilitytestability/[API readability and testability] is that the assertion we are making is not that great.

[source,csharp]
----

[Test]
public void ShouldConstructModelForSomeSituation()
{
	Assert.AreEqual(DateTime.Today.ToDisplayFormat(), model.SomeDate());
}
----

It's not really obvious what the expected result is supposed to be except that it should be the 'DisplayFormat'. If that fails then we'll need to navigate to the 'ToDisplayFormat' method to work out what that method does.

I think it should be possible to immediately know why a test failed so that we can address the problem straight away without too much investigation.

In this example we changed the way the code was working which coincidentally allowed us to make the assertion more obvious.

[source,csharp]
----

[Test]
public void ShouldConstructModelForSomeSituation()
{
	Assert.AreEqual("10 Oct 2009", model.SomeDate());
}
----

http://erik.doernenburg.com/[Erik] pointed out another example of this a few weeks ago while we were working on some HTML helper code.

The tests in question looked roughly like this:

[source,csharp]
----

[Test]
public void ShouldConstructReadOnlyValue()
{
	var readOnlyValue = new HtmlHelper().ReadOnlyValue("someId", "someValue", 'someTextValue');

	...
	var expectedValue = new TestHtmlBuilder().AddLabel("someId", "someTextValue").AddHiddenField("someId", "someValue").Build();

	Assert.AreEqual(expectedValue, readOnlyValue);
}
----

The test reads reasonably nicely and it's fairly obvious what it is we're testing for.

The problem here is that we've hidden away our expectation and in this case we actually found out that the 'TestHtmlBuilder' had extra spaces in some places so all our assertions were incorrect and we didn't even know!

In addition we end up *duplicating the logic that the 'HtmlHelper' is doing* if we create test assertion helpers like these.

[source,csharp]
----

[Test]
public void ShouldConstructReadOnlyValue()
{
	var readOnlyValue = new HtmlHelper().ReadOnlyValue("someId", "someValue", 'someTextValue');

	...
	var expectedValue = @"<input type=""hidden"" id=""someId"" value=""someId"" /><label for=""someId"">someValue</label>";

	Assert.AreEqual(expectedValue, readOnlyValue);
}
----

The new test doesn't look as clean as the old one but the assertion is much more obvious so if it fails then we can quickly work out why.
Scala: Converting an input stream to a string
Date: 2009-10-26 06:32:24

I was playing around with Scala over the weekend and one thing that I wanted to do was get the data from a HTTP response as a string so that I could parse the xml returned.

The data source is fairly small so loading the stream into memory wasn't a problem.

http://www.lixo.org/[Carlos] pointed me to http://www.kodejava.org/examples/266.html[a bit of Java code that did this] and I converted it as literally as possible into Scala.

[source,scala]
----

 def convertStreamToString(is: InputStream): String = {
    val reader = new BufferedReader(new InputStreamReader(is));
    val sb = new StringBuilder();

    var line : String = null;
    try {
      while ((line = reader.readLine()) != null) {
        sb.append(line + "\n");
      }
    } catch {
      case e: IOException => e.printStackTrace();
    } finally {
      try {
        is.close();
      } catch {
        case e: IOException => e.printStackTrace();
      }
    }

    sb.toString();
  }
----

The problem with this bit of code becomes clear when we try to run it through the REPL:

[source,text]
----

7:warning: comparing values of types Unit and Null using `!=' will always yield true
             while ((line = reader.readLine()) != null) {
----

In Java the expression '(line = reader.readLine())' would return the value of 'reader.readLine()'  as far as I understand. We can then compare that to null.

In Scala the evaluation of that expression is 'Unit' so if we ever run this function we end up in an infinite loop and eventually run out of memory.

I rewrote this function making use of recursion to get around the problem:

[source,scala]
----

  def convertStreamToString(is : InputStream) : String = {
    def inner(reader : BufferedReader, sb : StringBuilder) : String = {
      val line = reader.readLine()
      if(line != null) {
        try {
          inner(reader, sb.append(line + "\n"))
        } catch {
          case e : IOException => e.printStackTrace()
        } finally {
          try {
            is.close()
          } catch {
            case e : IOException => e.printStackTrace()
          }
        }

      }
      sb.toString()
    }

    inner(new BufferedReader(new InputStreamReader(is)), new StringBuilder())
  }
----

The code is still peppered with error handling statements but it now allows us to convert the stream into a string.

Is there a better/cleaner/more Scala-esque way to do this?
The effect of adding new people to project teams
Date: 2009-10-21 18:06:47

I've read quite frequently about the challenges we will experience when adding new people onto teams, including Fred Brooks' 'http://www.markhneedham.com/blog/2009/04/11/the-mythical-man-month-book-review/[The Mythical Man Month]', but having seen quite a few new people join the project that I've been working on over the last few months I think there are actually some significant benefits they can provide.

I think the impact new people provide is particularly useful on a http://www.markhneedham.com/blog/2009/08/13/challenging-projects-and-the-five-stages-of-grief/[challenging project] where they may be able to have a much more immediate impact.

From my observations there seem to be two main ways that new people can positively impact a team:

== Driving for simplicity

I think that new people joining a team may well be the best placed to judge the quality of a code base. Since they have very little to no context of the decisions made they only have the code to tell them the story of the project so far.

As a result of this they are the best placed to tell whether or not the http://www.markhneedham.com/blog/2009/03/18/coding-make-it-obvious/[code has been written in an obvious way] because they will probably have trouble understanding what's going on if that isn't the case.

Although following certain design approaches can ease the reading of code for everyone on a team I think that after we spend a while dealing with a level of complexity it becomes normal for us and we don't feel the pain as much.

Having someone new come in and point this out is invaluable as it helps us to drive towards a more maintainable and easier to work with solution.

== Enthusiasm

Something else I noticed is that the level of enthusiasm that new people have is often much higher than people who may have been working on a project for an extended period of time and could be feeling a bit jaded.

They haven't fought the battles or experienced the pain that current team members may have done so they arrive with few preconceptions and a desire to improve the way that things are being done.

When combined with their desire to simplify the code, the impact these people have can be quite significant.

An added benefit is that enthusiasm is contagious so some of it is bound to rub off on other members of the team thereby leading to improved morale.

== In Summary

I actually found it quite surprising to notice the impact that new people can have because I'd previously been more inclined to believe that people who had worked on a project for longer would provide much more value.

From what I've seen new members to a team can provide a lot of value very quickly so it's certainly an approach worth keeping in mind.
Coding: Invariant checking on dependency injected components
Date: 2009-10-31 03:00:40

I've written a couple of times previously about http://www.markhneedham.com/blog/2009/10/29/coding-consistency-when-invariant-checking/[invariant checking] http://www.markhneedham.com/blog/2009/02/14/coding-assertions-in-constructors/[in constructors] and I had an interesting discussion with some colleagues recently around doing this type of defensive programming when the object in question has its dependencies injected by a container.

Quite often we would see code similar to this in a controller:

[source,java]
----

public class SomeController
{
	public SomeController(Dependency1 valueOne, Dependency2 valueTwo)
	{
		AssertThat.isNotNull(valueOne);
		AssertThat.isNotNull(valueTwo);
		// and so on
	}
}
----

Where 'SomeController' would have 'Dependency1' and 'Dependency2' set up in a Spring configuration file in this example.

I can't really see much benefit in this type of pre condition checking although http://twitter.com/raphscallion[Raph] pointed out that if we got the configuration for this bean wrong then having these assertions would allow us to get quicker feedback.

While that is true it seems to me that we would maybe achieve quicker feedback by a few seconds in return for the clutter that we end up creating in our code. We have to read those assertions every time we come to this class.

I would prefer to have some http://www.markhneedham.com/blog/2009/09/18/tdd-testing-with-generic-abstract-classes/[specific tests for the dependency injection container] if we're interested in getting quick feedback in that area.

That seems to be a cleaner solution than having these types of checks in production code or am I missing something?
DSLs: Violating the builder pattern
Date: 2009-10-12 22:20:16

I recently came across http://pragdave.blogs.pragprog.com/pragdave/2008/03/the-language-in.html[an interesting post by Dave Thomas] where he discussed several domain specific languages (DSLs) he's come across and suggests that a lot of them seem to be trying too hard to read like the english language instead of focusing on describing a vocabulary for their specific domain

Reading this post reminded me that I fell into this trap earlier in the year while doing some work to create a builder pattern in our code which didn't need to make use of a 'Build' method but instead would make use of http://www.markhneedham.com/blog/2009/02/22/c-implicit-operator/[C#'s implicit operator to automatically convert the builder to an object at the appropriate moment].

My motivation was to make the code more readable but the code actually ended up being quite misleading for anyone else who came across it.

When someone sees the builder pattern they have an expectation that the method chaining sequence should end with 'Build()' so by using the implicit operator I was essentially breaking a well defined DSL for creating new objects.

To add to our problems, we nearly always use 'var' to describe local variables in our code base so there we times when you couldn't tell if what you had was a 'Foo' or a 'FooBuilder'.

Quite frequently the implicit conversion only happens when the variable is passed into another method or construct which explicitly defines which value is needed.

[source,csharp]
----

[Test]
public void SomeRandomTest()
{	
	var foo = new FooBuilder().Foo("someValue");

	var someFoos = new Foo[] { foo };
}
----

In this example 'foo' is only implicitly converted to the type 'Foo' when it is put into the array and its actual type is 'FooBuilder'.

In terms of what I was trying to achieve I created a piece of code that was easier to read but more difficult to understand which means that it's not intention revealing http://twitter.com/sai_venkat/statuses/4624116366[as my colleague Sai Venkatakrishnan pointed out].

It was an interesting experiment but I think in the future I'll stick with the more obvious approach which is a bit more verbose but a bit more intention revealing as well.
Testing End Points: Integration tests vs Contract tests
Date: 2009-10-25 00:04:12

We recently changed the way that we test against our main integration point on the project I've been working on so that in our tests we retrieve the service object from our dependency injection container instead of 'newing' one up.

Our tests therefore went from looking like this:

[source,csharp]
----

[Test]
public void ShouldTestSomeService()
{
	var someService = new SomeService();
	// and so on
}
----

To something more like this:

[source,csharp]
----

[Test]
public void ShouldTestSomeService()
{
	var someService = UnityFactory.Container.Resolve<ISomeService>();
	// and so on
}
----

This actually happened as a side effect of another change we made to inject users into our system via our dependency injection container.

We have some 'authenticated services' which require the request to contain a SAML token for a valid user so it seemed to make sense to use the container in the tests instead of having to duplicate this piece of behaviour for every test.

We needed to add our fake authorised user into the container for our tests but apart from this the container being used is the same as the one being used in the production code.

Our tests are therefore now calling the services in a way which is much closer to the way that they are called in the code than was previously the case.

I think this is good as it was previously possible to have the tests working but then have a problem calling the services in production because something in the container wasn't configured properly.

The downside is that these tests now have more room for failure than they did previously and they are not just testing the end point which was their original purpose.

In a way what we have done is *convert these tests from being contract tests to integration tests*.

I like the new way but I'm not completely convinced that it's a better approach.
Coding Dojo #19: Groovy Traveling salesman variation 
Date: 2009-07-04 09:36:01

Our latest coding dojo involved working on a variation of the http://en.wikipedia.org/wiki/Travelling_salesman_problem[traveling salesman problem] in Groovy again.

== The Format

We had 8 people participating this week so we returned to the Randori format, rotating the pair at the keyboard every 7 minutes.

Give the number of people it might have actually been better to have a couple of machines and use the http://www.dtsato.com/blog/2008/10/29/uberdojo-sao-paulo-coding-dojo/[UberDojo format].

== What We Learnt

* The importance of *just getting started* stood out a lot for me in this dojo - there have been quite a few times when we've met intending to do some coding and spent so long talking about coding that we didn't end up writing anything. Luckily http://twitter.com/davcamer[Dave] took the lead in this dojo and got the ball rolling. The code we wrote originally wasn't perfect but it helped create the momentum to keep the session going so it was valuable in that way.
* Another interesting feature of dojos for me is that *it really doesn't matter if you make mistakes* - if you write really terrible code in a dojo it's probably a good thing since you'll probably not go and repeat the same mistake on a real project. I learnt a lot about the perils of not refactoring early enough and having too much state in our code from our http://www.markhneedham.com/blog/2009/02/12/coding-dojo-9-refactoring-isola/[Isola Dojo] a few months ago.
* We *refactored much earlier* than we normally do in this dojo and I think it worked really well for allowing us to progress later on. Often we fall into the trap of just chasing the green bar a bit too much and we forget to clean up the code after each cycle but we had that a bit better in this one. We also backed up a bit after around 3 cycles after realising that the code was becoming a bit horrific and spent 1 cycle working it into shape for the next one.
* We fell into the trap of going *several cycles with broken tests* while trying to do some redesign on the code - the steps were clearly not small enough! Later on we corrected this when refactoring the code into a more functional style by taking very small steps and running the tests after each small change - this was a far more effective approach.
* Although we were working in a dynamic language *it didn't feel that the conversations were that different when discussing the code* - we were still talking about types when working out what to do. I'm not sure whether this means we haven't quite got the idea of dynamic languages or whether there isn't such a big difference between the way you talk about your code in them.

== For next time

* We might continue with another problem in Groovy - it's been quite fun working in a language that runs on the JVM without the verbosity you sometimes get when writing Java code.