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!
