The ScratchPad

The Simpler Life 1.0

2006-07-03T23:46:00.000-04:00

I have no self-control. What started as a simple redesign of my old website turned into an endless year of tweaking and distraction. It ended in liberation.

For the better part of a year, I obsessed over the little design details of my blog. I read all about making access to information easy. I experimented with branding and identity and style. I lurked about in CSS and design forums. Tinkered. Cobbled. Forged.

Never happy with the results. Many designs in the dustbin. Why was I doing this?

Good question.

And like that, I realised I couldn't remember what I was doing. I wanted to write, not tweak. I woke up.

First thing to go - the original blog. I was spending so much time fiddling with the styles, admin settings, and all the other goodies that I was left with little time to actually add content. So goodbye old blog, hello Blogger. Free, configurable enough, but not enough to be distracting.

Next, I started using Backpack to store ideas to write about. When I get an idea, but can't write about it immediately, I send my Backpack a note. All my great ideas are carved into a safe place.

Momentum gathering, feeling free-er. Anthing else? What else can get scrubbed? What about all those lists I read everyday? My Gmail box has 15 filters for all the lists I don't read but wish I did. Easily fixed - Login to Yahoo! Groups and set all but the mighty few groups to 'no more email please'. Oh ya, delete a few thousand unread emails.

Speaking of blogs, I subscribe to a whole pile of them too. Not anymore. I had about 50 that I read (or tried to read). Whittled them down to 10.

Finally, I'm going document-free. I repaved my laptop recently, and as part of that, I didn't put any of my old files back on my machine. It turns out I'm not going back to the archives as much as I thought I would. And I'm using text files more. I've even been experimenting with one big text file.

I'm free. Free of the fiddling, tweaking, searching. Free of the guilt of not keeping up with all the info. And free to fill this new blog full of content.

Simpler life? Time will tell. For now, I'm back in control.

technorati tags:simple, tweaking, less

WriteRoom

2006-07-03T22:50:00.000-04:00

Would someone please create this for Windows? Now!

technorati tags:Software, Ideas

TDD and the Single Printer

2005-09-23T21:37:00.000-04:00

Disclaimer: This article does not show all code and possible refactorings. It gives just enough to show how a design for testable printing evolved.

Credit for the ideas here go to all members of my team who paired and collaborated on the reporting story.

Let's get started. Of course, that's the problem, isn't it? Where do you start when you don't know where to start? Well, me, I cheat. The XP community over at Yahoo! helped kick the brain into gear with some helpful starters.

So here's what I decided: For now, I'm going to focus on what I know how to test, and maybe that will help me figure out how to test the stuff I don't know how to test. Initial thinking is that I can probably figure out how to test-drive content and presentation, and maybe that will lead me to a testable design for the printing part.

Ok, enough talking, lets see some tests. I'm lazy, I want to test the easiest thing - for me, that's probably the content.


[TestFixture]
public class ContentTest
{
 [Test]
 public void SeldomReferredToStats(){
         Assert.IsTrue(false);
 }
}

Red! At least the NUnit framework works. Ok, so I'm going to try to get the content for the very first section of the report.

[TestFixture]
public class ContentTest
{
   [Test]
   public void SeldomReferredToStats()
   {
      Content content = new Content();
      Assert.AreEqual(670, content.YawnFactor);
   }
}

And now the Content class:


public class Content
{
   public int YawnFactor { get {return 670;} }
}

Green!

That wasn't too interesting. But to tell you the truth, the Content class was not that exciting. In the real application, it served as a place to gather a whole bunch of different objects that were alive in the system and turn them into content. For now, let's pretend that we wrote a bunch of tests that let us develop a Content class that provides us with all the text for the Seldom Referred-to Stats section. We'll revisit this class in a bit, when it gets more interesting.

Now that I've got this content, I have to do something with it. Looking at the report, it makes sense to divide the content from the way it is presented.


[TestFixture]
public class PresentationTest
{
 [Test]
 public void Title()
 {
   Presentation presentation = new Presentation();
   Assert.AreEqual("TPS Report", presentation.Title);
 }
}

public class Presentation
{
   public string Title { get {return "TPS Report";} }
}

Great. I've got a title. Now I need that title underlined and centered. Time to stop coding for a second and think about this. Looking at the report, I can see a title, a bunch of sections, and a footer. And to me, the title and footer are just sections, so maybe the report presentation is just a bunch of sections. Enough talking, let's do some walking.

[TestFixture]
public class SectionTest
{
 [Test]
 public void TitleSection()
 {
    Assert.AreEqual("TPS Report", section.Title);
 }
}

public class Section
{
  public string Title { get {return "TPS Report";} }
}

That passes. And there is duplication, which reminds me that I have to actually use the new class.


[TestFixture]
public class PresentationTest
{
  [Test]
  public void Title()
  {
     Presentation presentation = new Presentation();
     Assert.AreEqual("TPS Report", presentation.TitleSection.Title);
  }
}

public class Presentation
{
   private Section titleSection = new Section();
   public Section Title { get {return titleSection;} }
}

Looking good. I guess I could do one of two things. I could try to get the underline in there, or I could try to do the next section, because right now the Section class is pretty useless for anything but a title. Underlining interests me more, so I'm going to try that. I don't know how.


[TestFixture]
public class SectionTest
{
   [Test]
   public void TitleSection()
   {
      Section section = new Section();
      Assert.AreEqual("TPS Report", section.Title);
      Assert.AreEqual("-----", section.Line);
   }
}

public class Section
{
    public string Title { get {return "TPS Report";} }
    public string Line { get {return "-----";} }
}

Another pass, update the Presentation test:


[TestFixture]
public class PresentationTest
{
  [Test]
  public void Title()
  {
      Presentation presentation = new Presentation();
      Assert.AreEqual("TPS Report", presentation.TitleSection.Title);
      Assert.AreEqual("-----", presentation.TitleSection.Line);
  }
}

And green. If you are looking at this about now, and saying that the presentation test doesn't add much value, think again. It adds a very important piece of value. It says to me that the design is kind of wierd. I'm exposing data that maybe shouldn't be exposed. I'm not happy about that. Also, it tells me that if I keep going down this path without being careful, I may not get what I want. If that sounds kind of non-committal, it is. I don't know what is wrong, but I get the sense, even this early, that something doesn't jive. Let's keep going to see if we can find out what doesnt' work here.

So, maybe now would be a good time to figure out how to print. Not quite yet. One thing that is wrong is that I have some dead code. The Section class isn't employed at the moment, and in my books, that means it either gets used, or it gets tossed. Maybe I should have waited till I needed that class. In this case it did some good to start with it because it got the juices flowing and the confidence up.

Back to the code.


[TestFixture]
public class SectionTest
{
    [Test]
    public void TitleSection()
    {
       Section section = new Section();
       Assert.AreEqual("TPS Report", section.Title);
       Assert.AreEqual("-----", section.Line);
    }

    [Test]
    public void ContentSection()
    {
       Section section = new Section();
       Assert.AreEqual("Section Title", section.Title);
       Assert.AreEqual("A bit of content" section.Line);
    }
}

Red, of course. We need a way to set the title and content.


[Test]
public void ContentSection()
{
  Section section = new Section();
  section.Title = "Section Title";
  section.Line = "A bit of content";

  Assert.AreEqual("Section Title", section.Title);
  Assert.AreEqual("A bit of content" section.Line);
}

public class Section
{
  private string title;
  private string line;

  public string Title {
    get {return title;}
    set {title = value;}
  }

  public string Line {
    get {return line;}
    set {line = value;}
  }
}

That test passes now, but the TitleSection and Presentation tests fail. One at a time:


public class Presentation
{
  private Section titleSection = new Section();
  public Presentation()
  {
      titleSection.Title = "TPS Report";
      titleSection.Line = "-----";
  }
  public Section Title { get {return titleSection;}}
}

Presentation tests are now passing. What about that section test?


[Test]
public void TitleSection()
{
  Section section = new Section();
  section.Title = "TPS Report";
  section.Line = "-----";
  Assert.AreEqual("TPS Report", section.Title);
  Assert.AreEqual("-----", section.Line);
}

Hmmmm....


[Test]
public void TitleSection()
{
  Section section = new Section();
  section.Title = "TPS Report";
  section.Line = HorizontalLine;
  Assert.AreEqual("TPS Report", section.Title);
  Assert.AreEqual(HorizontalLine, section.Line);
}

private string HorizontalLine { get {return "-----";} }

Green now, and I have a new idea. There is a difference between the types of lines that are in a section. It seems as though a section can have a horizontal line or a text line. I'm going to put that on the back burner for a second or two. I think that what I really need to do is let a section have more lines.


public class SectionTest
{
 ...

 [Test]
 public void ContentSection()
 {
      Section section = new Section();
      section.Title = "Section Title";
      section.AddLine("A bit of content");
      section.AddLine("A bit more content");

      Assert.AreEqual("Section Title", section.Title);
      Assert.AreEqual("A bit of content" section.Lines[0]);
      Assert.AreEqual("A bit more content" section.Lines[1]);
 }
}

public class Section
{
  private string title;
  private ArrayList lines;

  public string Title {
    get {return title;}
    set {title = value;}
  }

  public string[] Lines { get {return (string[])lines.ToArray(typeof(string));}
  public void AddLine(string line) { lines.Add(line); }
}

Of course, this passes, the other tests fail, we refactor those, and they all pass. Now I feel a little better. But I don't like this code, in the Section test:


  section.AddLine(HorizontalLine);

Lets make it this:


  section.AddHorizontalLine();

And implement it this way


public class Section
{
 ...
 public void AddHorizontalLine() { AddLine("-----"); }
}

Time for a recap of all the classes:


public class Section
{
 private string title;
 private ArrayList lines;

 public string Title {
    get {return title;}
    set {title = value;}
 }

 public string[] Lines { get {return (string[])lines.ToArray(typeof(string));}
 public void AddLine(string line) { lines.Add(line); }
 public void AddHorizontalLine() {lines.Add("-----") }
}

public class Presentation
{
 private Section titleSection = new Section();
 public Presentation()
 {
   titleSection.Title = "TPS Report";
   titleSection.AddHorizontalLine();
 }
 public Section Title { get {return titleSection;} }
}

public class Content
{
 public int YawnFactor { get {return 670;} }
 ...
}

Time to make that Content class a full contributor. Some of my team mates would have axed it already, since it's not being used anywhere but inside of a test.


[TestFixture]
public class PresentationTest
{
 [Test]
 public void TPSReport()
 {
    Presentation presentation = new Presentation(new Content());
    Assert.AreEqual("TPS Report", presentation.TitleSection.Title);
    Assert.AreEqual("-----", presentation.TitleSection.Lines[0]);
    Assert.AreEqual("Seldom Referred-to Stats",         presentation.SeldomReferredToStatsSection.Title);
    Assert.AreEqual("Yawn Factor:\t\t\t\t\t670",    presentation.SeldomReferredToStatsSection.Lines[0]);
    Assert.AreEqual("Average of a Bunch of Averages:\t\t\t\t\t1", presentation.SeldomReferredToStatsSection.Lines[1]);
    Assert.AreEqual("Sleep Quotient\t\t\t\t\tPurple", presentation.SeldomReferredToStatsSection.Lines[2]);
 }
}

public class Presentation
{
 private Section titleSection = new Section();
 private Content content;
 public Presentation(Content content)
 {
     titleSection.Title = "TPS Report";
     titleSection.AddHorizontalLine();
     this.content = content;
 }
 public Section Title { get {return titleSection;} }

 public Section SeldomReferredToStatsSection
 {
    get
    {
      Section section = new Section();
      section.Title = "Seldom Referred-to Stats";
      section.AddLine("Yawn Factor:\t\t\t\t\t" + content.YawnFactor);
      section.AddLine("Average of a Bunch of Averages:\t\t" + content.AverageOfAverages);
      section.AddLine("Sleep Quotient\t\t\t\t\t" + content.SleepQuotient);
      return section;
    }
 }
}

That passes. Notice I took out the title test in the Presentation test. It wasn't needed anymore. While doing that last test, I noticed some more refactoring that could be done. That silly titleSection needs to go:


public class Presentation
{
 private Content content;
 public Presentation(Content content)
 {
     this.content = content;
 }

 public Section Title {
 {
    get
    {
        Section section = new Section();
        section.Title = "TPS Report";
        section.AddHorizontalLine();
        return section;
    }
 }

 public Section SeldomReferredToStatsSection
 {
    get
    {
        Section section = new Section();
        section.Title = "Seldom Referred-to Stats";
        section.AddLine(content.YawnFactor);
        section.AddLine(content.AverageOfAverages);
        section.AddLine(content.SleepQuotient);
        return section;
    }
 }
}

That's a little better. But why am I distiguishing between the Title section and the SeldomReferredToStatsSection? It's an iffy call. I could leave it because it is readable. But I have an idea about how to refactor my tests that I can't give up:


public class Presentation
{
  private Content content;
  public Presentation(Content content)
  {
       this.content = content;
  }

  public Section[] Sections {
      get{return new Section[] {Title, SeldomReferredToStatsSection};}
  }

  private Section Title {
     get
     {
        Section section = new Section();
        section.Title = "TPS Report";
        section.AddHorizontalLine();
        return section;
      }
  }

  private Section SeldomReferredToStatsSection{
      get
      {
          Section section = new Section();
          section.Title = "Seldom Referred-to Stats";
          section.AddLine("Yawn Factor:\t\t\t\t\t" + content.YawnFactor);
          section.AddLine("Average of a Bunch of Averages:\t\t" + content.AverageOfAverages);
          section.AddLine("Sleep Quotient\t\t\t\t\t" + content.SleepQuotient);
          return section;
       }
  }
}

Now I can do this:


[TestFixture]
public class PresentationTest
{
 Section sectionUnderTest;

 [Test]
 public void TPSReport()
 {
    Presentation presentation = new Presentation(new Content());

     sectionUnderTest = presentation.Sections[0];
     CheckTitle("TPS Report");
     CheckLine(0, "-----");

     sectionUnderTest = presentation.Sections[1];
     CheckTitle("Seldom Referred-to Stats");
     CheckLine(0, "Yawn Factor:ttttt670");
     CheckLine(1, "Average of a Bunch of Averages:tt1");
     CheckLine(2, "Sleep QuotienttttttPurple");
 }

 private void CheckTitle(string expected)
 {
     Assert.AreEqual(expected, sectionUnderTest.Title);
 }

 private void CheckLine(int line, string expected)
 {
     Assert.AreEqual(expected, sectionUnderTest.Lines[line]);
 }
}

I like that! Now that I have a bit of a report, it's time, I think, to start printing. This is where I step back and say, what do we have and where can we go?

Well, printers print reports, don't they? I guess we could start there. First, I need a printer. I still don't know how to test printing, so I'm going to start by creating my own printer that's not really a printer.


[TestFixture]
public class MyOwnPrinterTest
{
   private string expectedReport = "TPS Report\r\n" +
                                   "-----\r\n" +
                                   "Yawn Factor\t\t\t\t\t670\r\n" +
                                   "Average of a Bunch of Averages:\t\t1\r\n" +
                                   "Sleep Quotient\t\t\t\t\tPurple";

   [Test]
   public void PrintReport()
   {
       Presentation presentation = new Presentation(new Content());
       MyOwnPrinter printer = new MyOwnPrinter();
       printer.Print(presentation);
       Assert.AreEqual(expectedReport, printer.PrintedPage);
   }
}

public class MyOwnPrinter
{
 public StringWriter Page;

 public void Print(Presentation presentation)
 {
    foreach (Section section in presentation.Sections)
    {
          Page.WriteLine(section.Title);
          foreach (string line in section.Lines)
               Page.WriteLine(line);
    }
 }
}

I knew that putting all the sections into an array would make sense. So there we have it. We have our report printing to a fake printer. But we aren't done yet. We need this to go to a real printer. The reason I made the fake printer first was simple - make sure the report can be printed. If a fake printer can define an interface to print the report to a stream, then the real printer can implement the same interface and change the underlying mechanics.

But, once again, I'm not happy. We are so close, but the interface doesn't seem right. For instance, how can I draw '-----' as a nice horizontal line on a real printer? I probably have the interface wrong. Let's think about this for a minute.

What does a printer do? It prints reports, right? Well, that was my first thought. But really, a printer is just like a monitor or even a web browser. And all those things provide services for rendering images. If that's the case, then maybe I have the relationship between Presentation and MyOwnPrinter backwards. Maybe Presentation draws itself using the services that MyOwnPrinter offers.

Lets try that. I feel a big refactoring coming on.


[TestFixture]
public class MyOwnPrinterTest
{
  private string expectedReport = "TPS Report\r\n" +
                                  "-----\r\n" +
                                  "Yawn Factor\t\t\t\t\t670\r\n" +
                                  "Average of a Bunch of Averages:\t\t1\r\n" +
                                  "Sleep Quotient\t\t\t\t\tPurple";

   [Test]
   public void PrintReport()
   {
       Presentation presentation = new Presentation(new Content());
       MyOwnPrinter printer = new MyOwnPrinter();
       presentation.To(printer);
       Assert.AreEqual(expectedReport, printer.PrintedPage);
   }
}

public class Presentation
{
   private Content content;
   public Presentation(Content content) {
        this.content = content;
   }

   public Section[] Sections {
      get{return new Section[] {Title, SeldomReferredToStatsSection};}}

   public void To(MyOwnPrinter printer)
   {
      foreach (Section section in Sections){
         printer.Render(section.Title);
         foreach (string line in section.Lines)
            printer.Render(line);
      }
   }

   private Section Title {
      get{
         Section section = new Section();
         section.Title = "TPS Report";
         section.AddHorizontalLine();
         return section;
      }
   }

   private Section SeldomReferredToStatsSection {
      get{
         Section section = new Section();
         section.Title = "Seldom Referred-to Stats";
         section.AddLine("Yawn Factor:ttttt" + content.YawnFactor);
         section.AddLine("Average of a Bunch of Averages:tt" + content.AverageOfAverages);
         section.AddLine("Sleep Quotientttttt" + content.SleepQuotient);
         return section;
         }
   }
}

public class MyOwnPrinter
{
  public StringWriter Page;

  public void Render(string line)
  {
     Page.WriteLine(line);
  }
}

I like that better. MyOwnPrinter now doesn't know about Presenation or it's structure. It just knows how to print stuff. Cool. But that still doesn't fix the problem of printing horizontal lines on a real printer. So maybe a service that the printer offers is to print horizontal lines. Before I even write a test for that, I don't want to have a bunch of 'if string == '-----' ' code everywhere. Maybe it's time to go back to that idea of lines.


[TestFixture]
public class HorizontalLineTest
{
 [Test]
 public void HorizontalLine()
 {
    MyOwnPrinter printer = new MyOwnPrinter();
    printer.Render(new HorizontalLine());
    Assert.AreEqual("-----", printer.Page);
  }
}

This will seem a little tricky, but here is what is in my head - the printer knows how to draw a horizontal line, and the HorizontalLine class uses the printer. Watch:


public class HorizontalLine
{
 public void Draw(MyOwnPrinter printer)
 {
     printer.RenderHorizontalLine();
 }
}

and then add the service to the printer:


public class MyOwnPrinter
{
  public StringWriter Page;

  public void Render(string line)
  {
    Page.WriteLine(line);
  }

  public void RenderHorizontalLine()
  {
    Render("-----");
  }
}

And we have a green bar. And I love that design, because now I can see how to extend it a little and make any line draw itself by extracting the Draw method into an abstract class.

Let's refactor a bit to use that concept:


public class Section
{
 private string title;
 private ArrayList lines;

 public string Title {
    get {return title;}
    set {title = value;}
 }

 public Line[] Lines { get {return (Line[])lines.ToArray(typeof(Line));}
 public void AddLine(string line) { lines.Add(new TextLine(line)); }
 public void AddHorizontalLine() {lines.Add(new HorizontalLine()) }
}

The test can no longer access the data directly because it is nice and encapsulated. Remember that test refactoring earlier? Maybe that can help:


public void TestHelper
{
 Section sectionUnderTest;
 MyOwnPrinter printer;

 [SetUp]
 public void SetUp()
 {
    printer = new MyOwnPrinter();
 }

  protected void CheckTitle(string expected)
  {
     sectionUnderTest.Title.Draw(printer)
     Assert.AreEqual(expected, printer.Page );
  }

  protected void CheckLine(int line, string expected)
  {
     sectionUnderTest.Lines[line].Draw(printer)
     Assert.AreEqual(expected, printer.Page);
  }
}

Use it in the Section Test:


public class SectionTest : TestHelper
{

[Test]
public void TitleSection()
{
   Section section = new Section();
   section.AddTitle("TPS Report");
   section.AddHorizontalLine();
   sectionUnderTest = section;
   CheckTitle("TPS Report");
   CheckLine(0, HorizontalLine);
}

[Test]
public void ContentSection()
{
   Section section = new Section();
   section.AddTitle("Section Title");
   section.AddLine("A bit of content");
   section.AddLine("A bit more content");
   sectionUnderTest = section;
   CheckTitle("Section Title");
   CheckLine(0, "A bit of content");
   CheckLine(1, "A bit more content");
 }

 private string HorizontalLine { get {return "-----";} }
}

And the Presentation test:


[TestFixture]
public class PresentationTest:TestHelper
{
[Test]
public void TPSReport()
{
    Presentation presentation = new Presentation(new Content());
    sectionUnderTest = presentation.Sections[0];
    CheckTitle("TPS Report");
    CheckLine(0, "-----");

    sectionUnderTest = presentation.Sections[1];
    CheckTitle("Seldom Referred-to Stats");
    CheckLine(0, "Yawn Factor:ttttt670");
    CheckLine(1, "Average of a Bunch of Averages:tt1");
    CheckLine(2, "Sleep QuotienttttttPurple");
}
}

and refactor the classes:


public class Presentation
{
 private Content content;
 public Presentation(Content content)
 {
    this.content = content;
 }

 public Section[] Sections {
   get{return new Section[] {Title, SeldomReferredToStatsSection};}}

 public void To(MyOwnPrinter printer)
 {
   foreach (Section section in Sections) {
       printer.Render(section.Title);
       foreach (Line line in section.Lines)
          printer.Render(line);
     }
  }

  private Section Title {
     get {
        Section section = new Section();
        section.AddTitle("TPS Report");
        section.AddHorizontalLine();
        return section;
     }
  }

  private Section SeldomReferredToStatsSection{
      get {
        Section section = new Section();
        section.AddTitle("Seldom Referred-to Stats");
        section.AddLine("Yawn Factor:ttttt" + content.YawnFactor);
        section.AddLine("Average of a Bunch of Averages:tt" + content.AverageOfAverages);
        section.AddLine("Sleep Quotientttttt" + content.SleepQuotient);
        return section;
      }
   }
}

public class Section
{
 private ArrayList lines;
 public Line[] Lines { get {return (Line[])lines.ToArray(typeof(Line));}
 public void AddTitle(string title){ AddLine(title)};
 public void AddLine(string line) { lines.Add(new TextLine(line)); }
 public void AddHorizontalLine() {lines.Add(new HorizontalLine()) }
}

And done. Well almost, I need to add a real printer. I think it's safe to extract an interface from my own printer:


public abstract class Printer
{
 public virtual void Render(string text){}
 public virtual void RenderHorizontalLine(){}
}

Any printer that implements that interface can now be used to print presentations. You will see the final refactoring in the class recap at the end. We've finally come down to the very bottom - using a real printer to print. And really, it shouldn't be too hard to create a class that represents the real printer. In this case, I'm going to show you the class first, pseudo-coded:


public class RealPrinter : Printer
{
 Graphics printerSurface;
 public override Render(string text)
 {
    printerSurface.DrawString(text);
 }

 public override RenderHorizontalLine()
 {
    printerSurface.DrawLine(...)
 }
}

Pass that to the Presentation class, and everything should draw. But where is the test? Ok, this may seem a little anti-climactic, but to test this, we write a very simple test:


[TestFixture]
public class RealPrinterTest
{
[Test]
public void LookAtTPSReport()
{
   Presentation presentation = new Presentation(new Content());
   LookAt(presentation);
}

private void LookAt(Presentation presentation)
{
   presentation.To(printer);
   System.PrintPreview();
}
}

(GRIN) I hope you haven't gotten this far, expecting an out of this world way of testing the actual printed page, only to feel like strangling me because I am using the print preview capabilities of the .Net framework (which I have pseudo-coded here because it is really not important to understanding the design).

However, the reason we feel confident doing this is because we have used TDD to drive every single part of the design right down to the interface to the printer. So we know that the lines, sections, and layout work properly before putting ink on the paper. By the time we get to the printer, we are dealing with a thin wrapper around graphics calls. And we don't test low level graphics calls to the OS because we won't be changing that stuff. What we have done is isolated the printer as much as possible so that we could have confidence in every other piece of the design.

So that's it for now. I'm not going to publish how we put the graphics or tabular elements on the page, or how we did the footers, or pagination, or any other detail. I have to maintain some element of mystery. And I need to keep my job, so I can't give away all our secrets to the public :) Look me up on the XP mailing list if you have questions about those things (hint - it's the same as all the other lines).

Here is a recap of all classes, sans tests:


public abstract class Printer
{
 public virtual void Render(string text){}
 public virtual void RenderHorizontalLine(){}
}

public class RealPrinter : Printer
{
 Graphics printerSurface;
 public override Render(string text)
 {
   printerSurface.DrawString(text);
 }

 public override RenderHorizontalLine()
 {
   printerSurface.DrawLine(...)
 }
}

public class MyOwnPrinter : Printer
{
 public StringWriter Page;

 public override void Render(string line)
 {
    Page.WriteLine(line);
 }

 public override void RenderHorizontalLine()
 {
    Render("-----");
 }
}

public class Presentation
{
 private Content content;
 public Presentation(Content content)
 {
   this.content = content;
 }

 public Section[] Sections {
   get{return new Section[] {Title, SeldomReferredToStatsSection};}}

 public void To(Printer printer)
 {
    foreach (Section section in Sections) {
         printer.Render(section.Title);
         foreach (Line line in section.Lines){
            printer.Render(line);
         }
 }

 private Section Title {
    get {
       Section section = new Section();
       section.AddTitle("TPS Report");
       section.AddHorizontalLine();
       return section;
    }
 }

 private Section SeldomReferredToStatsSection {
    get {
       Section section = new Section();
       section.AddTitle("Seldom Referred-to Stats");
       section.AddLine("Yawn Factor:ttttt" + content.YawnFactor);
       section.AddLine("Average of a Bunch of Averages:tt" + content.AverageOfAverages);
       section.AddLine("Sleep Quotientttttt" + content.SleepQuotient);
       return section;
    }
 }
}

public class Section
{
 private ArrayList lines;
 public Line[] Lines { get {return (Line[])lines.ToArray(typeof(Line));}
 public void AddTitle(string title){ AddLine(title)};
 public void AddLine(string line) { lines.Add(new TextLine(line)); }
 public void AddHorizontalLine() {lines.Add(new HorizontalLine()) }
}

public class HorizontalLine
{
 public void Draw(Printer printer)
 {
    printer.RenderHorizontalLine();
 }
}

public class Content
{
...
public int YawnFactor { get {return 670;} }
}

TDD and the Single Printer: Introduction

2005-09-21T21:34:00.000-04:00

Test-driving some development is impossible. Ok, really hard. Alright, not hard, but really tedious. Ok, not tedious, but...

I find myself going through that loop of thought when I don't know how to start using TDD on a programming problem. The catch is, TDD is perfect for exactly this type of development!

And so, I present my latest problem to which I thought I could not possibly use TDD, but ended up using it to create a very nice design, the likes of which will not be rivalled in all of programming lore! Ok, that's stretching it a bit, but the design made me happy, and in my books that counts for something.

Here's the story: Print an unmodifiable report to the printer when the user hits the 'Print' button. Use the following mockup as a guide:

The mockup above contains all the elements of the real report that we were asked to add to the real product. And so the story begins...

Next time: Where do we start?!?!

Incentive To Change

2005-08-12T21:32:00.000-04:00

Summer's a good time to catch up on some reading. A book, a blog, and a radio program have reshaped some of my thinking about agility.

Freakonomics is one of those books that makes you want to ask questions. Deep questions. Economist Steven Levitt, one of books authors, makes the claim that he wants to shed light on the ideal world and expose the actual world. And he does this brilliantly by asking the right types of questions and not shying away from the results. From why drug dealers live with their mothers, to real estate agents and their ability to move homes, right down to the way people name their children, there is usually and answer different from the one that you expected to get. The thing that was striking, and that started me down a path of thought, was that all of those unexpected answers had a common flavour - they all focused on incentive structures that cause people to do the things that they do.

Text and Code Don't Mix

2005-06-14T21:31:00.000-04:00

I just got over a nasty case of string duplication. My current code was littered with strings that represented tags, attributes, and XPath queries, and over a very short time, the buildup resulted in some big time duplication of text.

No problem, right? Wrong! What I thought would take me an hour or so to remove ended up taking my pair and me around 6 hours! Like code duplication, I've learned that string duplication can be everywhere - embedding common string patterns in other strings, and then extracting them later, is a huge pain in the neck. Using the same string in 15 different places is a big headache. And don't get me started on using hardcoded strings in tests. Before you know it, they are everywhere.

Here is what we learned as we refactored to remove hardcoded string duplication:
1) It's boring and mind-numbing.
2) Microsoft doesn't have any nice tools to help us .NET programmers yet. Search and Replace is primitive, and unless you are a regular expression guru, forget about using this tool effectively.
3) Make expression builders as early as you can to help build compound expressions where only part of the text in the string varies.

I'd give some code examples, but I've had a long day of removing hardcoded strings, and I'm going to bed.

My Favourite Smells

2005-05-25T21:29:00.000-04:00

Hi, I'm Chris, and I've written smelly code. In fact, I still do it. I mean, you can't remove code smells if you don't put them there in the first place.

A recent conversation around continuous design and refactoring towards a good design got me thinking along a tangent- are there smells that I have a hard time escaping? What are the ones that I can't seem to shake, no matter how hard I try?

So I came up with one that I am especially fond of, and that special place in my heart goes to primitive obsession. This is the smell that I use all the time. What is it? Well, it's when you use primitive types, like doubles, strings, ints, to represent ideas that really deserve their own type.

My brain doesn't always detect the need for a new type. Sometimes I am perfectly content to represent something, say, like the concept of Mass, as a double. All over the system, I merrily use my 'Mass is a double' notion, until....

I need a tolerance!?! You never told me I needed a tolerance! Now I need to go around the system and change all my Masses to use a tolerance... ok, done, not so bad... What!? I need to convert my Mass to Energy?!?! Why didn't you tell me?! Ok, why is this not working? Those darn tolerances are messing everything up!

This is a semi-regular occurence, and I personally find two things interesting about primitive obsession.

It is easy to live with for a while, sometimes a long while. But it tangles itself into a system nice and tight, and is one of the hardest smells to remove.
If avoided, your code is so easy to change and you get some nice side benefits.

Let me give an example of the latter point. I work on a system that has a mixture of one-based indices and zero-based indices (legacy, gotta live with it). As we built the new stuff, we decided everything would be one-based. However, there were all kinds of errors popping up. Anyone who has programmed for more than a week will concur (hopefully, or I'm the only fool who can't add and subtract) that i + 1 and i - 1 all over the place get's really hard to figure out after a while, and your head spins while trying to convert zero-based and one-based indices back and forth. Never mind all the guess work when trying to figure out if a parameter to a method was zero or one based.

Well, I tried something. I made a OneBasedInt and a ZeroBasedInt value type and began using them everywhere. Soon, there were all kind of cool things happening:

People suddenly knew the type of index they should pass into a method
Things started to fail fast - I could no longer assign zero to a one-based index, and I could tell exactly when I was doing that!
No more index + 1 and index - 1 all over the code.

So much for my weakness(es). I see the benefits of avoiding primitive obsession, but continue to get stung by it often. Maybe I will be old and wise one day. For now, I will relish my small victories.

Architecture & Agility: Strange Bedfellows?

2005-05-07T21:28:00.000-04:00

Raise your hand if you have heard the following: An astounding 65% of defects are traced back to requirements and the cost of repairing defects grows exponentially throughout the software development lifecycle.

Sound familiar? Many companies that sell requirements training services use a similar sounding pitch, and it's supported by a gaggle of studies. The numbers, the adjectives, and adverbs vary, but the message is the same: bad or changing requirements lead to costly changes down the road.

I've been down that road. After enough projects, you realize that getting a requirement wrong can have costly after-effects. So the answer is to nail down those requirements right away, right?

Well, not entirely. The loathing a programmer has towards changing and incorrect requirements began so long ago that it's almost genetic. Before studies and companies told us that there would be bad and changing requirements, we created protection mechanisms. That protection mechanism (and not coincidently, the dirtiest two word combination in the entire agile software universe) is software architecture.

I and countless others have built software architectures to try to anticipate the unexpected. What will they ask for next? I know the requirements will likely be incorrect, so I'll build for every possibility. And of course, this was costly, because my deck of software tarot cards was always missing a card or two, so I couldn't accurately predict everything, and would have to munge, hack and kludge new features, all the while pointing out how great my architecture was.

Along comes agility and XP. Concerning requirements, XP says we know that the requirements will change, according to changing business needs and priorities, but, we won't build our software with any type of prognostication or speculation. Test-driven development, refactoring, and simple design will ensure our code will be supple and changeable to support those changing business needs when those future needs turn into present reality.

This approach works. I'll be the first to stand up and say it works because I've tried it. And for the requirements that you know about and take into consideration, you have a fantastic chance for success.

The kicker is the part about 'requirements that you know about and take into consideration'. Onsite customers take lot's of things into consideration. Usability studies, product identity, prioritized features. For standalone products that have no inter-relation with other products in a company, this is about all the onsite customer needs to consider. But this isn't so with an increasing amount of software products.

That's were I posit that there are more requirements than meets the eye of the typical (product manager or domain expert) onsite customer. And sometimes we incorrectly label these unseen requirements as speculative or forward-looking, when reality says these requirements are present, but hidden. After some reflecting, I think that there are domain, economic, process, social and technological requirements that go beyond what the traditional onsite customer has the capability to see.

Let's take a look at an experience I've had. I'll change the name of all the components to protect the identity of the products I work on, but the essentials are the same.

Before adopting XP, a colleague of mine and I began designing the next generation of our platform. This platform would serve as the foundation for a number of products that would be created over the next few years. In our domain, there are entities known as Pixies, Gremlins, Brownies, and Imps. Every application that is built in our domain is concerned with Pixies, Gremlins, Brownies, and Imps. What we knew about each application, even though they weren't built yet, was that even though each application uses these entities, they each assume different things about the relationships between them. For instance, our PixieDust application assumes that there are PixieBags filled with Pixies. Our PixieMagic application, however, assumes that Pixies come in PixieBoxies, and specific Pixies are kept in PixieCompartments in the PixieBoxies. We also had to build the platform so that other, external companies could build their own applications.

What we realized is that each application had it's own domain, and used it's own language. And what each language boiled down to was a domain specific query for Pixies, Gremlins, Brownies, and Imps. So, the known requirement was to build a platform that could support domain specific queries. This was a domain requirement that spanned a number of products. We also felt that using a service-oriented architecture would allow us to build a system that could change over time without affecting the innumerable applications that were built at external companies.

When we started XP, we were told to throw away that architecture. We'd be building a domain model for the PixieDust application, and since the PixieMagic, FurryGremlin, and ImpishDelight apps weren't starting for another six months, we'd worry about them at that point. That domain would serve as the start of the platform, and when other applications started, they would help drive the application.

So we went full force down that path. We were already convinced that XP would help us keep the model supple and light enough to change.

Fast forward 18 months later. The ImpishDelight and FurryGremlin applications started up at the same time, and the definite start date for PixieMagic was in three months. The two new project teams saw the platform domain model that had been built declared that it was only good for the PixieDust application, and the way it assumed Pixies and Brownies were stored and the containment relationships made no sense in their domains.

At that point, onsite customers and programmers from each of the project teams got together and came to the conclusion, independent of our earlier forays, that the best way to handle multiple applications was a service-oriented architecture that allowed applications to submit domain specific queries.

The work to convert the PixieDust application to use a new platform model that we are still trying to develop is now more expensive than if we'd started along that path oh so many months ago.

Some would say thats ok. The onsite customer knew all the costs associated with their decision and are willing to live with it. Pish posh say I. I say I work for the same company, and expensive decisions affect my bonus and retirement plans, so I'm not willing to live with it.

Some would say, well, if you really knew, you should have started building towards it. To that I say the culture of XP labels anything that is not in the present 'speculation'. And speculation is a mortal sin in XP, and you are cast out like a leper if you suggest it.

Of course, that's a bit of an exaggeration, but it also isn't far from the truth. But looking back, and seeing what we knew for sure, there were business requirements that went far beyond the 'I need to see that the Pixie Dust created is 99% pure and has no Impish Influence'. That type of business requirement is hard to see for an onsite customers, but easy to see from the perspective of the technical staff.

As I said before, I believe that there are domain, economic, process, social and technological requirements on projects that need consideration. Make no mistake, these are also business requirements because they are related to building what is needed. I've already explored the domain requirements and alluded to the fact that there were technological requirements - service oriented architectures are based on message-oriented systems and I won't go into the technical details here. Other technical requirements were the ability to communicate and integrate with external systems and platforms. For instance, we were building on .Net, but a growing base of our customers are moving to open source tools like Java, Eclipse, Linux, Ruby, Python. Shipping a .NET only platform would isolate them. Once again, this was a requirement that was technical, outside the domain of Pixies and Imps. Some would argue, and rightly so, that a proxy customer in tune with the market would not be a stranger to these facts.

How about an economic requirement? Each time a change was made to the domain model, multiple projects would feel the impact in terms of lost time converting vertical applications to use the new domain changes. The ImpishDelight team shielded itself from these changes by maintaining an anti-corruption layer (a facade that sat on top of the platform). PixieDust was more exposed to the platform, and so any change to the domain model would ripple through the entire code base.

Change was costly. As more projects came online, and began putting design pressure on the platform, changes to the domain model would ripple through more and more projects. The question surrounding this requirement was one of direct cost: How could the natural change associated with developing an ever-changing domain model be kept low? This requirement, of course, was met by the eventual solution.

Which brings about another requirement - process. Following XP, teams practice evolutionary development, simple design, and refactoring. However, these practices are about incremental steps. Experience thus far, with all other forces considered, is that the design oscillates rather than evolves. It jumps from one state to another to another, without settling into a mode where it grows. As new projects are added, there seemed to be no end to the flip-flopping from one design to the next, in search of one that will accommodate all domains. Once again, it seemed as though we were trying to do the impossible - find an object-oriented domain model that accommodated all applications being built. Eric Evans wrote about subdomains and the like in his book Domain Driven Design. We tried some of those techniques, but fell short each time. Guess what? The SOA solution worked here too.

And that brings us to the final requirement - social. Each team believes that they are correct in their assumptions about their domain. Rightfully so, each team defends their viewpoints, fearing that important details may be left out if a compromise was made and a more general model was built. Vigorous defence of specific views of the world have been exhibited by all teams - PixieDust’s defence of the United Order of Pixies standard as the domain language. ImpishDelight's stance on Imps and ImpJobs. PixieMagic's zeal over not using PixieID's. FurryGremlin's insistence on using PixieID's. The list goes on and on. Whoever concedes loses a precious piece of their domain.

Another piece of the social requirement that drives domain development is the fact that multiple teams need to work on the platform at once. However, because of distance, unfamiliarity, and fear that one team will undo the changes of another, this is was not a generally accepted practice. All changes to the platform had to be funnelled through the PixieDust team for approval, putting an extra burden on one team to coordinate the work of multiple teams.

After all that, where do we go now? Ok, here goes - software architecture. Before you pull the pin on the Holy Hand Grenade of Antioch and lob it my way, please listen!

I'm not talking about the traditional software architect who hands out designs from the Ivory Tower while making sure they don't mess their white robes with the mundane task of coding. No, my view is that software architecture is important to agility because it really defines a technical customer role who is also a programmer on the team. The requirements are not easy to get right, we know that, and XP does a good job at managing the change associated with changing business requirements. What an agile architect does is guide the discovery of those hidden requirements that the business facing customer doesn't always see and that the programmers naively label as speculative.

The agile architect helps to define the requirements for things that won't happen for a while (but definitely will happen), and will be more costly to implement if they are forgotten altogether. So why do I call this software architecture? Because ultimately, I think it's these types of requirements that help draw a better, bigger picture of the software that is being produced. And that better, bigger picture is the context in which simple design, refactoring, and TDD happen. Without that picture, refactoring and simple design is just a bunch of quantum, unrelated steps within the framework of current software features without a goal that says 'hey, wait, there are things that you need to consider here because they are happening or will be happening with 100% certainty'.

I don't think that my colleague and I came up with a design that just happened to be the same as the one that was independently discovered over a two year period. I'm not that lucky. It really boils down to the fact that agile teams need architectural guidance just as much as they need business guidance.

Ok, count to three, no more, no less, and lobbest thou thy Holy Hand Grenade of Antioch towards thou foe.

People Come, People Go

2005-04-21T21:27:00.000-04:00

A friend of mine, Gunjan, came by today. He's visiting for a day or two and we both realised he hadn't seen our project area in close to a year. As we were chatting, I introduced him to some of the new team members and something dawned on me - of the original 6 programmers on the team, only one other programmer and myself were left, and our programming complement had increased to 8!

That meant that over the course of a year, we had welcomed 6 new programmers and said goodbye to 4. Those four are coaching other projects now - we were the first to use XP in our shop, and so naturally, the people on it were used to help other projects use XP too.

Getting back to the people changes... I've been on lots of projects, and rarely does this type of turnover happen without turbulence. This was a different experience.

As we got word that someone new was joining us, we made no special preparations. When the day arrived, it was business as usual. Pairs formed, they picked tasks, and went to work. No one was assigned to pair with our new team mate, the pairs just formed naturally. No special orientation happened - the pair would talk about things that seemed different or strange to our XP neophyte, but that was the extent of the training. All necessary skills and habits were gained by observation, lore, and participation.

This worked incredibly well. All who have joined are solid in the team's practices. And they in turn have been instrumental at bringing new people onto the team.

Change doesn't always come in the form of evolving software requirements. Most times it comes in ways that we can't anticipate. A year ago, Gunjan told me that agility means adapting to all kinds of change. If I'd been told that meant that we'd have 6 new people who had no XP experience in exchange for 4 productive, XPerienced programmers, I would have said that our project was doomed.

Good thing I kept my mouth shut, because I couldn't have been more wrong.

Project:1, Integration Machine: 0

2005-04-11T21:26:00.000-04:00

Something cool happened on our project today. The integration machine died. Hard-drive just up and kicked the bucket.

Why is this cool? Because 2 minutes later, we had a new integration machine! In the past, the build machine dying would have been a major catastrophe. All the special little tools, the wierd paths and environment variables, the database setup, the special security settings... oh, the headache after hours of reinstallation and twiddling to make it all work again.

That was the past. Today, we just went over to another machine, deleted the project directory, did a CVS get, nant, and presto! New build machine! And not a headache in sight.

This is due to one important practice: we maintain our build as diligently as any of our code. We make sure all the tools are in CVS, all the code in CVS is in pristine, shippable condition, and all tests are running green. And every member of the team knows how to modify the build scripts. No buildmaster is needed.

We also make sure that the build can run fresh, on any machine at anytime. So next time you have to spend a few hours reconfiguring a new build (or integration) machine, consider whether you can spend some time making your build run anywhere, anytime, anyhow, by anyone. You'll be thankful you did.

Commitment

2005-04-05T21:25:00.000-04:00

After talking about Points vs. Pair Hours for a bit, I was surprised by the web of topics that are entangled with estimation and planning. Here's a brief synopsis of some of my thoughts around just one of those knots - commitment.

Commitment is a strange beast. I've heard it said more than once that on XP and agile projects we don't make commitments, that they are 'specious as best' as one well-known agilista says. I don't agree. Here's why.

Commitment makes a few other words come to mind - dedication, trust, integrity, honesty, promise. When my team makes a plan on Friday afternoon for the following week, all those things come into play as we strive to meet that plan. We are effectively making a promise to deliver working, tested, features, and we do all we can to deliver those working, tested features.

Along the way, the various facets of commitment come alive. The team is dedicated to completing the stories. All members work together with stories on the plan as the focal point. We remove obstacles that get in the way of delivering, whether they are technical, process, or social roadblocks. The teams actions reflect the commitment to do what they said they would do. And when anything goes awry of the plan, complete and full disclosure occurs.

This is commitment. This delivers on promises. This builds trust.

Where I think people get tripped up is when they think that commitment only means a number on a schedule. The past was painful, for everyone - programmers, customers, managers. It was every (wo)man for themself. Meet the schedule, or suffer. And do it by any means possible. That was commitment. Commit to a number.

I've seen teams move beyond this definition of commitment, and into a productive, trust-building definition of commitment. It requires dedication, and it requires vulnerability on each team members part. In the end, it's worth it.

Some more points about 'Points' (and pair hours)

2005-04-02T21:17:00.000-05:00

My post about NUTs vs. pair hours generated some response and some further questions. Here are a selection of those comments.

Laurent Bossavit writes:

I would think that any story estimates can come from:
estimates made at the start of the project, when we estimate all stories for the purpose of making a Release Plan

One thing I didn't mention is that we estimated all stories in team
weeks at the beginning of a project, not NUTs. That's how we were
taught. The theory is that at the beginning of a project you don't
have the same learning, experience, and facts about the story as you
do when you decide to begin the story. The further you are away from
completion, the less time and effort you spend on estimating, and
therefore, the courser the estimate is.

Laurent continues:

Did you at any time re-estimate the entire collection of (not yet completed) stories in the project ?

All the time. We do this because we learn new things about the
software that we are building, and things that we do over time could
potentially make things easier or harder to do. My experience is
that, over time, we tend to get better estimates when we are
revisiting the stories.

Another benefit of revisiting the stories is that the stories change.
We may think of new, cheaper alternatives to give the customer what is
needed. Or sometimes user feedback has been received and we no longer
need a story, or need to change it.

There are so many factors that affect what a story is and how long it
will take to complete that we've found it beneficial to constantly
revisit the release plan. The time you spend doing this pays for
itself.

Joshua Kerievsky got in on the action:

Can you further explain what you mean by "we measure the hours that were spent programming, and the number of hours that were accepted as stories." A few examples would help.

Sure... Let's say I had 5 stories, and we said each would take 5
hours. At the end of the iteration, two stories took 10 hours, and
were finished. 3 stories took 4 hours, and were finished, but not
accepted (for whatever reason). We would say that 22 hours were spent
programming, and 10 hours were accepted by customers. We also track
the number of stories accepted. In this case, 2 stories were
accepted, 3 weren't.

Joshua continues:

I'm just not clear on what the "budget" is per iteration and how that budget changes from iteration to iteration.

The budget is the number of hours spent programming. In the example
above, the budget would be 22 hours. We use the capacity of the
programmers to set the budget. All other numbers are used to find
areas where we need to improve.

More Josh? Ok, one more:

I'd also like to know what you do mid-iteration, when a story is clearly going to go over its estimate. What kind of budgeting or negotiation happens then?

We do what we always did - talk to the customer, renegotiate, drop
stories if needed. If a 5 hour story looks like it will take 10, we
ask the customer where they want to re-adjust to compensate for the
extra 5 hours (drop a 5 hour story, get something simpler, etc). We
then retrospect on the story in iteration planning.

The whole discussion can be read on the Extreme Programming group over at Yahoo! Thanks for all who got involved - I learned a lot!

Using the Right Measure: Pair Hours vs. NUTs

2005-03-28T21:12:00.000-05:00

What's the best way for a team to estimate work? I'm not sure there is one correct answer that fits every team. Some advocate a point system, others say using actual time is the best way. Kent Beck, in XPE2 seems to come out in favour of the latter. I've tried both and want to share some of my learning.

But first, a little story. I like to build things out of wood whenever I get some free time. I'm no craftsman, by any stretch. But I like the diversion from my usual work. And I get to turn perfectly good pieces of wood into large piles of useless scrap, with the occasional by-product looking sort of like what I intended it to be.

This past Christmas, I built two toolboxes, one for each of my wife's brothers. By some strange alignment of the planets, they came out looking pretty much exactly the same, and I had some fun building them.

All kidding aside, over the years I've discovered that a few things are important when building things out of wood. You need sharp tools. Good lighting is very helpful. But most important, you need a good measure. Whether it's a tape measure, a builder's square, or a length of scrap, consistent measurement is your best friend when producing, and reproducing, good quality pieces.

Software development is the same way. Good estimation, and delivering according to those estimates, is important for a software team. Imagine a team that says they will deliver something, and then delivers it. And now imagine that team could do that consistently, week after week. This is, after all, what XP and all the agile schools try to get teams to do, isn't it? Make a promise and then keep a promise.

The story I tell is about my team. I think that my team is much like any other. We come from a company who didn't always deliver software when it promised, and when that software was delivered, it didn't have all the features in it that were originally promised either. Trust was not that high. Morale wasn't much higher.

When we learned how to estimate, XP style, the NUT (Nebulous Unit of Time) was used. What is a NUT, you may ask? Well, the snappy answer is 'smaller than a coconut, bigger than a walnut'. What that really means is that the NUT (or story point, if that's what you are used to) is an arbitrary unit used for one purpose - planning. I've been asked many times to explain exactly what a NUT is, to be more specific than the snappy answer I gave earlier. And as I have learned more about estimating with NUTs, I've formed a loose definition.

To me, a NUT is a unit that encapsulates a few elements related to planning. It consists of equal parts time, effort, and gut feeling. Notice that time is only one part of a NUT and is equal to the other ingredients.

There was an initial adjustment period when we began using NUTs for planning. Programmers were not used to using NUTs and always tried to attach a time value to the NUT. For instance, some would say - 'I think one NUT is about half a day of work, so 3 NUTs is about one and a half days worth of work'. But our mentors insisted that this was no different than using 'days' to estimate.

A bit of a breakthrough came when we began to see that NUT's were used to make relative estimates. Using a baseline, such as adding an OK button to dialog box, other stories could be estimated based on how much more or less time/effort/gut feeling it would take to accomplish. If the OK button story was one NUT, then adding a new options dialog might be two NUTs, if it felt twice as 'big' and changing the text on a dialog may be half a NUT, because it wasn't nearly as hard as adding an OK button.

Customers weren't used to using NUT's either. To be completely honest, I'm not sure that they ever got comfortable with the notion. But they tried. Similar to programmers, they would ask how to relate NUTs back to real time. 3 NUTs, that's about 2 days, right? That question was typical in our iteration planning. But like programmers, they began to see that NUTs were used to make relative estimates and soon were questioning (rightfully so) why one story was twice the NUT value as another story.

As time went on, we started to feel as though we got the hang of NUTs. A few simple rules were instituted. First, stories that were more than 5 NUTs were probably too big. That meant they needed to be broken down into smaller stories. Second, stories were broken into engineering tasks so that programmers could estimate more accurately by considering the steps in a story. Programmers would estimate individual engineering tasks in NUTs and add them up to get a NUT estimate for the entire story. Third, customers would use the velocity from the last iteration as the budget for the current iteration. And 4th, only stories that were accepted, by customers, as complete counted towards the velocity calculation.

The velocity calculation was interesting. Let's suppose that an iteration only had two stories, each with a value of 4 NUTs. The team finishes one story, and it takes 4 NUTs. The other story is not completed, but 3 NUTs were spent nonetheless. The budget of the next iteration would be 4 NUTs, not 7. Madness, you may say, but nay! There was a reasonfor this rule.

For our team, the most important thing was the delivery of finished stories. Therefore, we would only take credit for finished stories. Velocity, for us, was the number of NUTs it took us to finish stories. Suppose we got into a scenario where we had 4 stories, all 4 NUTs in size, and on each story we got 3 NUTs done, but no story was accepted ( we came close to this once or twice!!). Should we say our velocity was 12? It's a hard call, and some would say yes. But to us, not delivering a story meant you didn't get credit for it.

One last note on the structure of our iterations. Each iteration was 2 weeks in length, starting on Wednesday and ending two Wednesdays later. More on this later.

As time went on, the arbitrary value of the NUT started to have an effect on us. During iterations, we had a rule that we would negotiate if a story was going over the original estimate. If the story my pair and I were working on was estimated at 3 NUTs, but we felt that it was going to go over 3 NUTs, we'd let the customer know. At that point, we'd tell them how many more NUTs we'd need, say two NUTs in this case. The customer would then have some choices. They could remove a story from the iteration, valued at 2 or more NUTs. They could simplify the story. They could cancel the story altogether, and use the remaining story budget to add another, equally valued story. In the end, whatever the customer chose, the budget for the iteration could not be exceeded.

So where did the arbitrary nature of the NUT kick in? Well, it kicked in when the programmers tried to figure out how many extra NUTs they would need. 'We need two more NUTs', they'd say. 'How do you know that?', customers would ask. 'Because we have used two NUTs already, and think we'll need two more like those two', programmers respond. And customers would give them the NUTs needed. And the programmers would be done an hour or two later, and count the two NUTs in the final estimate.

But wait! Customers would say that the first two NUT's took a day to complete, and the next two only took a couple of hours! How can this be?!?

Well, say the programmers, NUTs aren't all about time. This was a tough story, and the effort was really high. So two extra NUTs is about right.

Over time, these conversations happened often. Almost daily. Customers eventually got weary - sure, take whatever extra you need. And programmers would justify less and less their need for extra budget - hey, it's just turning out to be harder than what we expected.

From iteration to iteration, velocity would fluctuate. Up, then down, then up again. And it never seemed to plateau. What was the cause?

A number of things, actually. First, NUTs are not constant. There is no frame of reference over time. Remember the story I told about making toolboxes out of wood? There was a reason. Imagine if I had a ruler that changed the size of an inch every time I need to make a measurement. I'd never be able to build the toolbox because the measurements would all be wrong. Similar thing with stories. The size of the NUT expands and contracts over the course of iterations. A 3 NUT story in iteration 10 is not always (rarely is) the same size as a 3 NUT story in iteration 20.

With no constant frame of reference, NUTs facilitated a lack of accountability. Didn't hit the velocity this iteration? Oh well, we finish what we finish. We didn't realise that this story would be 6 NUTs, not 3, it just wasn't the same as that other 3 NUT story that seemed so similar.

With no constant frame of reference, customers and programmers couldn't negotiate. Once again, the units on the measuring tape seemed to change each time it was picked up.

Another thing, not related to NUTs, was the iteration length and the start and end days of the iteration. Two weeks seemed like a long time. Most work didn't happen until the second week because the end was not in sight until later in the iteration. Starting on a Wednesday was also not helpful. After iteration planning, a bit of work would happen on Wednesday afternoon. Thursday, everyone was winding down the week, but the iteration was just beginning. Friday morning was hard, because the team used Friday afternoon as research time. Monday would come, and that would feel like the first day of the iteration, when in reality, it wasn't. Work all week. Hit the following Monday, and then rush to finish those stories because on Tuesday at 5PM, we ended the iteration.

It didn't feel natural. None of it.

Now this happened over the course of 13 months. But we wanted to give this an honest chance. Not to mention we felt that this was the right thing to do. We did all sorts of things to tweak the way we worked. We tried to break stories into smaller pieces. But how could you define small when you couldn't figure out the unit of measure? Small was relative. We tried different negotiation strategies, different ways of picking stories. All roads came back to NUTs.

The catalyst came in the form of XP Explained v.2. Reading about using pair hours, and one week iterations, the concepts seemed right. You could measure hours with a clock. You could tell what the halfway point was in an iteration and in a story. So, as a team, we decided to try it.

It wasn't met with open arms by everyone. There were fears. Wouldn't we be micro managing by tracking every hour? Couldn't you measure the productivity of individual programmers with pair hours? We can't start on Mondays, no one likes to do iteration planning on Monday morning.

But we pushed forward. To the teams credit, we just tried it. With one small modification. Instead of iteration planning on Monday morning, we have iteration planning at 10:30AM on Friday morning. We finish at lunch. And then we have research time. Monday morning we begin fresh on new stories. This had an unforeseen (and welcome) side effect - nobody went home on Friday worrying about a story that was unfinished.

So, what happened? Well, immediately we made two rules. No story could exceed 6 hours. And every story had to have business value to our customer. The second rule we had always followed. But when making very small stories, this rule had to be followed strictly. It meant challenging the entire team to barter for simple solutions, and to think about delivering the software in small increments of business value.

As we followed these rules, we saw that iteration planning was much quicker. Small stories are easier to estimate. And there was much less bickering and much more creative problem solving to get the largest amount of value for the least amount of hours.

The iteration became more productive. Stories would start in the morning and finish by days end, with customer acceptance shortly after. Programmers could easily track how long they took on a story, measuring the exact number of hours they spent on a story with a clock. It was easy to tell how a story was progressing, and negotiating changes with customers was more meaningful with a new and consistent currency - the pair-hour.

Finishing stories has a great motivating effect on the whole team. And finishing stories each day pushes the team to finish more stories. Fears that were expressed earlier never came to pass. No one is measured, no one is micro managed, and Mondays are a thing to look forward to.

That doesn't mean that we are entirely without challenges. Moving to one-week iterations, with small stories, put a large burden on our domain experts. It forced us to consider delivering a wider range of unrelated stories each iteration as opposed to a narrow scope of related stories in order to spread the work around.

We also noticed that we need more involvement from our testers in the definition of stories. There is just not the luxury of using long exploratory testing cycles to find defects. In fact, we have become increasingly intolerant of defects found in exploratory testing, especially if those defects are found after a story has been accepted by a customer.

Now, the way we measure velocity has changed. We still use yesterdays weather. But yesterdays weather is made up of more than just one measurement. It wasn't just 30 Celsius, it was also partly cloudy with a south wind blowing at 15km/h. With that in mind, we measure the hours that were spent programming, and the number of hours that were accepted as stories. Why do we do this? Well, velocity, as it was traditionally measured, seemed to only care about programmer performance. But if programmers finished all of their work, but the customers couldn't accept all the stories because of an abundance of meetings during the iteration, wouldn't that be interesting to know? And why not try to fix that issue instead of applying penalties to team? To that end, we always use the number of hours spent programming as our velocity, and do all that we can to make sure that the number of accepted story hours is equivalent. Perhaps this is not the most ideal definition of velocity, but it works for us now!

Most importantly though, as a whole team, we are now completely accountable for each story. In each iteration planning session, we retrospect on stories that were significantly over or significantly under the original estimates. Programmers and customers can give a complete accounting of why things happened the way they did, see what we need to improve so that we can get better at delivering stories each iteration.

In all, we've had a lot of good learning around using both systems of measurement. Our abandoning the point method of estimation in favour of the pair-hour system of estimation is not because one is superior to the other. We just found that the latter enabled the team to think of delivering business value in a different way. In so doing, we are making promises and keeping those promises - we deliver more consistently. And because we are using a good measuring tape in the shop, the pile of scrap stories isn't growing the way it used to.