Lately, I exchanged some arguments with Derick Bailey about some details of
the red-green-refactor cycle of
the Test-driven development process. In short,
the issue revolved around
the fact that it’s not enough to have a test red or green, but it’s also important to have it red or green for
the right reasons. While for me, it’s sufficient to initially have a NotImplementedException in place, Derick argues that this is not totally correct (see these two posts: Red/Green/Refactor, For
The Right Reasons and Red For
The Right Reason: Fail By Assertion, Not By Anything Else). And he’s right.
But on
the other hand, I had no idea how his insights could have any practical consequence for my own individual interpretation of
the red-green-refactor cycle (which is not really red-green-refactor, at least not in its pure sense, see
the rest of this article). This made me think deeply for some days now. In
the end I found out that
the ‘right reason’ changes in my understanding depending on what development phase I’m in.
To make this clear (at least I hope it becomes clear…) I started to describe my way of working in some detail, and then something strange happened:
The scope of
the article slightly shifted from focusing ‘only’ on
the ‘right reason’ issue to something more general, which you might describe as something like 'Doing real-world TDD in .NET , with massive use of third-party add-ins’.
This is because I feel that there is a more general statement about Test-driven development to make: It’s high time to speak about
the ‘How’ of TDD, not always only
the ‘Why’. Much has been said about this, and me myself also contributed to that (see here: TDD is not about testing, it's about how we develop software). But always justifying what you do is very unsatisfying in
the long run, it is inherently defensive, and it costs time and effort that could be used for better and more important things. And frankly: I’m somewhat sick and tired of repeating time and again that
the test-driven way of software development is highly preferable for many reasons - I don’t want to spent my time exclusively on stating
the obvious…
So, again, let’s say it clearly: TDD is programming, and programming is TDD. Other ways of programming (code-first, sometimes called cowboy-coding) are exceptional and need justification. – I know that there are many people out there who will disagree with this radical statement, and I also know that it’s not a description of
the real world but more of a mission statement or something. But nevertheless I’m absolutely sure that in some years this statement will be nothing but a platitude.
Side note: Some parts of this post read as if I were paid by Jetbrains (the manufacturer of
the ReSharper add-in – R#), but I swear I’m not. Rather I think that Visual Studio is just not production-complete without it, and I wouldn’t even consider to do professional work without having this add-in installed...
The three parts of a software component
Before I go into some details, I first should describe my understanding of what belongs to a software component (assembly, type, or method) during
the production process (i.e.
the coding phase). Roughly, I come up with
the three parts shown below:
First, we need to have some initial sort of requirement. This can be a multi-page formal document, a vague idea in some programmer’s brain of what might be needed, or anything in between. In either way, there has to be some sort of requirement, be it explicit or not. – At
the C# micro-level,
the best way that I found to formulate that is to define interfaces for just about everything, even for internal classes, and to provide them with exhaustive xml comments.
The next step then is to re-formulate these requirements in an executable form. This is specific to
the respective programming language. - For C#/.NET,
the Gallio framework (which includes MbUnit) in conjunction with
the ReSharper add-in for Visual Studio is my toolset of choice.
The third part then finally is
the production code itself. It’s development is entirely driven by
the requirements and their executable formulation. This is
the delivery,
the two other parts are ‘only’ there to make its production possible, to give it a decent quality and reliability, and to significantly reduce related costs down
the maintenance timeline.
So while
the first two parts are not really relevant for
the customer, they are very important for
the developer.
The customer (or in Scrum terms:
the Product Owner) is not interested at all in how
the product is developed, he is only interested in
the fact that it is developed as cost-effective as possible, and that it meets his functional and non-functional requirements.
The rest is solely a matter of
the developer’s craftsmanship, and this is what I want to talk about during
the remainder of this article…
An example
To demonstrate my way of doing real-world TDD, I decided to show
the development of a (very) simple Calculator component.
The example is deliberately trivial and silly, as examples always are. I am totally aware of
the fact that real life is never that simple, but I only want to show some development principles here…
The requirement
As already said above, I start with writing down some words on
the initial requirement, and I normally use interfaces for that, even for internal classes -
the typical question “intf or not” doesn’t even come to mind. I need them for my usual workflow and using them automatically produces high componentized and testable code anyway. To think about their usage in every single situation would slow down
the production process unnecessarily.
So this is what I begin with:
namespace Calculator
{
/// <summary>
/// Defines a very simple calculator component for demo purposes.
/// </summary>
public interface ICalculator
{
/// <summary>
/// Gets
the result of
the last successful operation.
/// </summary>
/// <value>The last result.</value>
/// <remarks>
/// Will be <see langword="null" /> before
the first successful operation.
/// </remarks>
double? LastResult { get; }
} // interface ICalculator
} // namespace Calculator
So, I’m not beginning with a test, but with a sort of code declaration - and still I insist on being 100% test-driven. There are three important things here:
Starting this way gives me a method signature, which allows to use IntelliSense and AutoCompletion and thus eliminates
the danger of typos - one of
the most regular, annoying, time-consuming, and therefore expensive sources of error in
the development process.
In my understanding,
the interface definition as a whole is more of a readable requirement document and technical
documentation than anything else. So this is at least as much about
documentation than about coding.
The documentation must completely describe
the behavior of
the documented element.
I normally use an IoC container or some sort of self-written provider-like model in my architecture. In either case, I need my components defined via service interfaces anyway. - I will use
the LinFu IoC framework here, for no other reason as that is is very simple to use.
The ‘Red’ (pt. 1)
First I create a folder for
the project’s third-party libraries and put
the LinFu.Core dll there. Then I set up a test project (via a Gallio project template), and add references to
the Calculator project and
the LinFu dll. Finally I’m ready to write
the first test, which will look like
the following:
namespace Calculator.Test
{
[TestFixture]
public class CalculatorTest
{
private readonly ServiceContainer container = new ServiceContainer();
[Test]
public void CalculatorLastResultIsInitiallyNull()
{
ICalculator calculator = container.GetService<ICalculator>();
Assert.IsNull(calculator.LastResult);
}
} // class CalculatorTest
} // namespace Calculator.Test
This is basically
the executable formulation of what
the interface definition states (part of).
Side note:
There’s one principle of TDD that is just plain wrong in my eyes: I’m talking about
the Red is 'does not compile' thing. How could a compiler error ever be interpreted as a valid test outcome? I never understood that, it just makes no sense to me. (Or, in Derick’s terms: this reason is as wrong as a reason ever could be…) A compiler error tells me: Your code is incorrect, but nothing more.
Instead,
the ‘Red’ part of
the red-green-refactor cycle has a clearly defined meaning to me: It means that
the test works as intended and fails only if its assumptions are not met for some reason.
Back to our Calculator. When I execute
the above test with R#,
the Gallio plugin will give me this output:
So this tells me that
the test is red for
the wrong reason: There’s no implementation that
the IoC-container could load, of course. So let’s fix that. With R#, this is very easy:
First, create an ICalculator - derived type:
Next, implement
the interface members:
And finally, move
the new class to its own file:
So far my ‘work’ was six mouse clicks long,
the only thing that’s left to do manually here, is to add
the Ioc-specific wiring-declaration and also to make
the respective class non-public, which I regularly do to force my components to communicate exclusively via interfaces: This is what my Calculator class looks like as of now:
using System;
using LinFu.IoC.Configuration;
namespace Calculator
{
[Implements(typeof(ICalculator))]
internal class Calculator : ICalculator
{
public double? LastResult
{
get
{
throw new NotImplementedException();
}
}
}
}
Back to
the test fixture, we have to put our IoC container to work:
[TestFixture]
public class CalculatorTest
{
#region Fields
private readonly ServiceContainer container = new ServiceContainer();
#endregion // Fields
#region Setup/TearDown
[FixtureSetUp]
public void FixtureSetUp()
{
container.LoadFrom(AppDomain.CurrentDomain.BaseDirectory, "Calculator.dll");
}
...
Because I have a R# live template defined for
the setup/teardown method skeleton as well,
the only manual coding here again is
the IoC-specific stuff: two lines, not more…
The ‘Red’ (pt. 2)
Now,
the execution of
the above test gives
the following result:
This time,
the test outcome tells me that
the method under test is called. And this is
the point, where Derick and I seem to have somewhat different views on
the subject: Of course,
the test still is worthless regarding
the red/green outcome (or: it’s still red for
the wrong reasons, in that it gives a false negative). But as far as I am concerned, I’m not really interested in
the test outcome at this point of
the red-green-refactor cycle. Rather, I only want to assert that my test actually calls
the right method. If that’s
the case, I will happily go on to
the ‘Green’ part…
The ‘Green’
Making
the test green is quite trivial. Just make LastResult an automatic property:
[Implements(typeof(ICalculator))]
internal class Calculator : ICalculator
{
public double? LastResult { get; private set; }
}
One more round…
Now on to something slightly more demanding (cough…). Let’s state that our Calculator exposes an Add() method:
...
/// <summary>
/// Adds
the specified operands.
/// </summary>
/// <param name="operand1">The operand1.</param>
/// <param name="operand2">The operand2.</param>
/// <returns>The result of
the additon.</returns>
/// <exception cref="ArgumentException">
/// Argument <paramref name="operand1"/> is < 0.<br/>
/// -- or --<br/>
/// Argument <paramref name="operand2"/> is < 0.
/// </exception>
double Add(double operand1, double operand2);
} // interface ICalculator
A remark: I sometimes hear
the complaint that xml comment stuff like
the above is hard to read. That’s certainly true, but irrelevant to me, because I read xml code comments with
the CR_Documentor tool window. And using that, it looks like this:
Apart from that, I’m heavily using xml code comments (see e.g. here for a detailed guide) because there is
the possibility of automating help generation with nightly CI builds (using MS Sandcastle and
the Sandcastle Help File Builder), and then publishing
the results to some intranet location. This way, a team always has first class, up-to-date technical
documentation at hand about
the current codebase.
(And, also very important for speeding up things and avoiding typos: You have IntelliSense/AutoCompletion and R# support, and
the comments are subject to compiler checking…).
Back to our Calculator again: Two more R# – clicks implement
the Add() skeleton:
...
public double Add(double operand1, double operand2)
{
throw new NotImplementedException();
}
} // class Calculator
As we have stated in
the interface definition (which actually serves as our requirement document!),
the operands are not allowed to be negative. So let’s start implementing that. Here’s
the test:
[Test]
[Row(-0.5, 2)]
public void AddThrowsOnNegativeOperands(double operand1, double operand2)
{
ICalculator calculator = container.GetService<ICalculator>();
Assert.Throws<ArgumentException>(() => calculator.Add(operand1, operand2));
}
As you can see, I’m using a data-driven unit test method here, mainly for these two reasons:
Because I know that I will have to do
the same test for
the second operand in a few seconds, I save myself from implementing another test method for this purpose. Rather, I only will have to add another Row attribute to
the existing one.
From
the test report below, you can see that
the argument values are explicitly printed out. This can be a valuable
documentation feature even when everything is green: One can quickly review what values were tested exactly -
the complete Gallio HTML-report (as it will be produced by
the Continuous Integration runs) shows these values in a quite clear format (see below for an example).
Back to our Calculator development again, this is what
the test result tells us at
the moment:
So we’re red again, because there is not yet an implementation…
Next we go on and implement
the necessary parameter verification to become green again, and then we do
the same thing for
the second operand. To make a long story short, here’s
the test and
the method implementation at
the end of
the second cycle:
// in CalculatorTest:
[Test]
[Row(-0.5, 2)]
[Row(295, -123)]
public void AddThrowsOnNegativeOperands(double operand1, double operand2)
{
ICalculator calculator = container.GetService<ICalculator>();
Assert.Throws<ArgumentException>(() => calculator.Add(operand1, operand2));
}
// in Calculator:
public double Add(double operand1, double operand2)
{
if (operand1 < 0.0)
{
throw new ArgumentException("Value must not be negative.", "operand1");
}
if (operand2 < 0.0)
{
throw new ArgumentException("Value must not be negative.", "operand2");
}
throw new NotImplementedException();
}
So far, we have sheltered our method from unwanted input, and now we can safely operate on
the parameters without further caring about their validity (this is my interpretation of
the Fail Fast principle, which is regarded here in more detail).
Now we can think about
the method’s successful outcomes. First let’s write another test for that:
[Test]
[Row(1, 1, 2)]
public void TestAdd(double operand1, double operand2, double expectedResult)
{
ICalculator calculator = container.GetService<ICalculator>();
double result = calculator.Add(operand1, operand2);
Assert.AreEqual(expectedResult, result);
}
Again, I’m regularly using row based test methods for these kinds of unit tests.
The above shown pattern proved to be extremely helpful for my development work, I call it
the Defined-Input/Expected-Output test idiom: You define your input arguments together with
the expected method result. There are two major benefits from that way of testing:
In
the course of refining a method, it’s very likely to come up with additional test cases. In our case, we might add tests for some edge cases like ‘one of
the operands is zero’ or ‘the sum of
the two operands causes an overflow’, or maybe there’s an external test protocol that has to be fulfilled (e.g. an ISO norm for medical software), and this results in
the need of testing against additional values. In all these scenarios we only have to add another Row attribute to
the test.
Remember that
the argument values are written to
the test report, so as a side-effect this produces valuable
documentation. (This can become especially important if
the fulfillment of some sort of external requirements has to be proven).
So your test method might look something like that in
the end:
[Test, Description("Arguments: operand1, operand2, expectedResult")]
[Row(1, 1, 2)]
[Row(0, 999999999, 999999999)]
[Row(0, 0, 0)]
[Row(0, double.MaxValue, double.MaxValue)]
[Row(4, double.MaxValue - 2.5, double.MaxValue)]
public void TestAdd(double operand1, double operand2, double expectedResult)
{
ICalculator calculator = container.GetService<ICalculator>();
double result = calculator.Add(operand1, operand2);
Assert.AreEqual(expectedResult, result);
}
And this will produce
the following HTML report (with Gallio):
Not bad for
the amount of work we invested in it, huh? - There might be scenarios where reports like that can be useful for demonstration purposes during a Scrum sprint review…
The last requirement to fulfill is that
the LastResult property is expected to store
the result of
the last operation. I don’t show this here, it’s trivial enough and brings nothing new…
And finally: Refactor (for
the right reasons)
To demonstrate my way of going through
the refactoring portion of
the red-green-refactor cycle, I added another method to our Calculator component, namely Subtract(). Here’s
the code (tests and production):
// CalculatorTest.cs:
[Test, Description("Arguments: operand1, operand2, expectedResult")]
[Row(1, 1, 0)]
[Row(0, 999999999, -999999999)]
[Row(0, 0, 0)]
[Row(0, double.MaxValue, -double.MaxValue)]
[Row(4, double.MaxValue - 2.5, -double.MaxValue)]
public void TestSubtract(double operand1, double operand2, double expectedResult)
{
ICalculator calculator = container.GetService<ICalculator>();
double result = calculator.Subtract(operand1, operand2);
Assert.AreEqual(expectedResult, result);
}
[Test, Description("Arguments: operand1, operand2, expectedResult")]
[Row(1, 1, 0)]
[Row(0, 999999999, -999999999)]
[Row(0, 0, 0)]
[Row(0, double.MaxValue, -double.MaxValue)]
[Row(4, double.MaxValue - 2.5, -double.MaxValue)]
public void TestSubtractGivesExpectedLastResult(double operand1, double operand2, double expectedResult)
{
ICalculator calculator = container.GetService<ICalculator>();
calculator.Subtract(operand1, operand2);
Assert.AreEqual(expectedResult, calculator.LastResult);
}
...
// ICalculator.cs:
/// <summary>
/// Subtracts
the specified operands.
/// </summary>
/// <param name="operand1">The operand1.</param>
/// <param name="operand2">The operand2.</param>
/// <returns>The result of
the subtraction.</returns>
/// <exception cref="ArgumentException">
/// Argument <paramref name="operand1"/> is < 0.<br/>
/// -- or --<br/>
/// Argument <paramref name="operand2"/> is < 0.
/// </exception>
double Subtract(double operand1, double operand2);
...
// Calculator.cs:
public double Subtract(double operand1, double operand2)
{
if (operand1 < 0.0)
{
throw new ArgumentException("Value must not be negative.", "operand1");
}
if (operand2 < 0.0)
{
throw new ArgumentException("Value must not be negative.", "operand2");
}
return (this.LastResult = operand1 - operand2).Value;
}
Obviously,
the argument validation stuff that was produced during
the red-green part of our cycle duplicates
the code from
the previous Add() method. So, to avoid code duplication and minimize
the number of code lines of
the production code, we do an Extract Method refactoring. One more time, this is only a matter of a few mouse clicks (and giving
the new method a name) with R#:
Having done that, our production code finally looks like that:
using System;
using LinFu.IoC.Configuration;
namespace Calculator
{
[Implements(typeof(ICalculator))]
internal class Calculator : ICalculator
{
#region ICalculator
public double? LastResult { get; private set; }
public double Add(double operand1, double operand2)
{
ThrowIfOneOperandIsInvalid(operand1, operand2);
return (this.LastResult = operand1 + operand2).Value;
}
public double Subtract(double operand1, double operand2)
{
ThrowIfOneOperandIsInvalid(operand1, operand2);
return (this.LastResult = operand1 - operand2).Value;
}
#endregion // ICalculator
#region Implementation (Helper)
private static void ThrowIfOneOperandIsInvalid(double operand1, double operand2)
{
if (operand1 < 0.0)
{
throw new ArgumentException("Value must not be negative.", "operand1");
}
if (operand2 < 0.0)
{
throw new ArgumentException("Value must not be negative.", "operand2");
}
}
#endregion // Implementation (Helper)
} // class Calculator
} // namespace Calculator
But is
the above worth
the effort at all? It’s obviously trivial and not very impressive. All our tests were green (for
the right reasons), and refactoring
the code did not change anything. It’s not immediately clear how this refactoring work adds value to
the project. Derick puts it like this:
STOP! Hold on a second… before you go any further and before you even think about refactoring what you just wrote to make your test pass, you need to understand something: if your done with your requirements after making
the test green, you are not required to refactor
the code. I know… I’m speaking heresy, here. Toss me to
the wolves, I’ve gone over to
the dark side! Seriously, though… if your test is passing for
the right reasons, and you do not need to write any test or any more code for you class at this point, what value does refactoring add?
Derick immediately answers his own question:
So why should you follow
the refactor portion of red/green/refactor? When you have added code that makes
the system less readable, less understandable, less expressive of
the domain or concern’s intentions, less architecturally sound, less DRY, etc, then you should refactor it.
I couldn’t state it more precise. From my personal perspective, I’d add
the following:
You have to keep in mind that real-world software systems are usually quite large and there are dozens or even hundreds of occasions where micro-refactorings like
the above can be applied. It’s
the sum of them all that counts. And to have a good overall quality of
the system (e.g. in terms of
the Code Duplication Percentage metric) you have to be pedantic on
the individual, seemingly trivial cases.
My job regularly requires
the reading and understanding of ‘foreign’ code. So code quality/readability really makes a HUGE difference for me – sometimes it can be even
the difference between project success and failure…
Conclusions
The above described development process emerged over
the years, and there were mainly two things that guided its evolution (you might call it eternal principles, personal beliefs, or anything in between):
Test-driven development is
the normal, natural way of writing software, code-first is exceptional. So ‘doing TDD or not’ is not a question. And good, stable code can only reliably be produced by doing TDD (yes, I know: many will strongly disagree here again, but I’ve never seen high-quality code – and high-quality code is code that stood
the test of time and causes low maintenance costs – that was produced code-first…)
It’s
the production code that pays our bills in
the end. (Though I have seen customers these days who demand an acceptance test battery as part of
the final delivery. Things seem to go into
the right direction…).
The test code serves ‘only’ to make
the production code work. But it’s
the number of delivered features which solely counts at
the end of
the day - no matter how much test code you wrote or how good it is.
With these two things in mind, I tried to optimize my coding process for coding speed – or, in business terms: productivity - without sacrificing
the principles of TDD (more than I’d do either way…). As a result, I consider a ratio of about 3-5/1 for test code vs. production code as normal and desirable. In other words: roughly 60-80% of my code is test code (This might sound heavy, but that is mainly due to
the fact that software development standards only begin to evolve.
The entire software development profession is very young, historically seen; only at
the very beginning, and there are no viable standards yet. If you think about software development as a kind of casting process, where
the test code is
the mold and
the resulting production code is
the final product, then
the above ratio sounds no longer extraordinary…)
Although
the above might look like very much unnecessary work at first sight, it’s not. With
the aid of
the mentioned add-ins, doing all
the above is a matter of minutes, sometimes seconds (while writing this post took hours and days…).
The most important thing is to have
the right tools at hand. Slow developer machines or
the lack of a tool or something like that - for ‘saving’ a few 100 bucks - is just not acceptable and a very bad decision in business terms (though I quite some times have seen and heard that…). Production of high-quality products needs
the usage of high-quality tools. This is a platitude that every craftsman knows…
The here described round-trip will take me about five to ten minutes in my real-world development practice. I guess it’s about 30% more time compared to developing
the ‘traditional’ (code-first) way. But
the so manufactured ‘product’ is of much higher quality and massively reduces maintenance costs, which is by far
the single biggest cost factor, as I showed in this previous post: It's
the maintenance, stupid! (or: Something is rotten in developerland.). In
the end, this is a highly cost-effective way of software development…
But on
the other hand, there clearly is a trade-off here: coding speed vs. code quality/later maintenance costs.
The here described development method might be a perfect fit for
the overwhelming majority of software projects, but there certainly are some scenarios where it’s not - e.g. if time-to-market is crucial for a software project. So this is a business decision in
the end. It’s just that you have to know what you’re doing and what consequences this might have…
Some last words
First, I’d like to thank Derick Bailey again. His two aforementioned posts (which I strongly recommend for reading) inspired me to think deeply about my own personal way of doing TDD and to clarify my thoughts about it. I wouldn’t have done that without this inspiration. I really enjoy that kind of discussions…
I agree with him in all respects. But I don’t know (yet?) how to bring his insights into
the described production process without slowing things down.
The above described method proved to be very “good enough” in my practical experience. But of course, I’m open to suggestions here…
My rationale for now is: If
the test is initially red during
the red-green-refactor cycle,
the ‘right reason’ is: it actually calls
the right method, but this method is not yet operational. Later on, when
the cycle is finished and
the tests become part of
the regular, automated Continuous Integration process, ‘red’ certainly must occur for
the ‘right reason’: in this phase, ‘red’ MUST mean nothing but an unfulfilled assertion - Fail By Assertion, Not By Anything Else!
