Memory Lane

An article back from the grave.

Today I stumbled upon an old article I wrote on our team wiki titled “Project Proposal – A Generic Approach to TDD”.  I had leveraged the TDD formula in a couple earlier projects and this was an attempt at informing my current team how we could leverage it in our current project.  After re-reading it I figured there is some useful content worth posting in my blog even though my opinion on some things have changed since then.  I think it is good enough just the way it it is and does not need to be perfect.  So with a little obfuscation on project names, here it is…

 

Project Proposal – A Generic Approach to TDD

March 13, 2006

Description

The engineering team has tentatively agreed to utilize the Test Driven Development (TDD) methodology in an effort to ensure the quality & testability of the proposed ProjectB enhancements. Now that ProjectA is almost gold it is time for the team to start discussing how it is going to implement this methodology. Once the initial investigation is over, and focus shifts from research to design, it is important that we as a development team have a clear understanding of how we plan to accomplish TDD. In short, to facilitate success, we need to agree on the techniques & tools we will use.

Objectives and Benefits

This proposal is only meant to spur discussion, thought, & ideas about how we will administer TDD. The proposals’ purpose is to drive the team toward a unified understanding of what we will do, & how we will do it. With a collective understanding of TDD we will be successful in implementing it. Not everything that should be discussed is included in this proposal (e.g. test frame work, legacy code test integration, code coverage, error tests, test reviews, etc.).

Development Requirements

Here is my initial listing of our TDD requirements for ProjectB (to be discussed and expanded by the development team):

1. New code needs to be testable via automated unit & integration tests.
2. Old code needs to support automated unit & integration tests.
3. Tests need to be run-able at any time, by anyone on the development team.
4. Test results need to be stored in a repository.
5. When a test fails, the appropriate people must be informed.
6. We want to create a class structure which makes testing as easy as possible.

Definitions:

Unit test: Engineering test which occurs at the class/method level of code.
Integration test: Test which spans multiple classes/methods.

The Approach

When designing a TDD solution from scratch, integrating one in to existing code, or working with legacy code, the approach is the same:

1. Write the test. Watch it fail.
2. Write the code. Watch the test pass.
3. Run the unit test suite. Watch it pass.
4. Refactor. Repeat.

Since the team has not discussed and agreed upon a test frame work (e.g. Boost Unit Test Library), I will not get in to the implementation details of each step.  I would like to mainly focus on step 2 (Write the code).  To some degree, steps 1 (write the test) & 4 (Refactor) will also be touched on.  I can discuss these steps without knowledge of the implemented test suite.

When writing code it is important that we focus on simplicity. Simplicity leads towards understandability & maintainability of the system. We’ve all heard of the ‘KISS‘ principle and its usefulness. KISS becomes critical when automated testing is considered. A complex system yields complex tests, and hence a greater chance for defects to occur both in the code & in the tests.

In order to apply KISS, you need to know what ‘complex’ is. Two methods in a system which may implement similar behavior could be vastly different in complexity. In order for the team to use KISS and tackle complexity we need a way to measure code complexity. Cyclomatic complexity is a software metric designed to measure the general complexity of code. Its goal is to identify code which is ‘complex’ by measurement. For example, a method by default has a CC (Cyclomatic Complexity) of 1. If you add an ‘if’ statement to that method, add 1 to the methods CC. Adding an ‘else’ to the ‘if’ statement adds 1 to the CC. The method now has a CC measurement of 3, and is measurably more complex then a method which has a CC of 1.

Why is CC useful? It has two main benefits. One, it allows the development team to understand which code (new & legacy) is complex and subject to refactoring. Two, it identifies the number of base tests which are required. The CC index is a reflection of the number of code paths through a section of code. Since a properly designed test is supposed to test all paths through code, the CC index is an accurate reflection of the number of tests required to test that code.

Since simplicity leads to maintainability and a reduction in defects, a CC index will allow the team to identify code which is not simple and flag it for refactoring (step 4 above).

Now that we have a technique for identifying complex systems (the ‘what’), the next step is ‘how’. How do we create simple software systems (i.e. Low CC code)? The answer is to create code in which methods and classes are isolated and loosely depended on each other. Following patterns like Strategy & Factory Method will act as a guide.

For example, let’s assume that you have a small method with a CC of 5. This would require 5 unit tests to correctly test the code paths through the method. Using the Factory Method Pattern, the method can be refactored to a CC of 1 and 4 additional classes or methods have been created, which are now isolated, require smaller tests (each have a CC of 1), are easier to understand, and are less defect prone. Applying the Factory Method Pattern to a method with a CC of 5 does not make the benefits apparent, but anyone who has worked on ProjectA code has seen methods which would have CC indexes of 25+. In cases like these, the Factory Method Pattern would make sense. If it’s easier to test, it’s easier to identify and resolve defects.

Conclusion

What I’ve done above is outlined a basic approach to identify and reduce complex code for the purpose of testing. With up to 4 different engineers working in the ProjectB code, simple, loosely coupled code will be a team performance advantage.

Summary

1. Focus on KISS principle.
2. Use Cyclomatic complexity to identify complex code for potential refactoring, & the number of tests required.
3. Create/Refactor in to simple, isolated, fine-grained code using Strategy & Factory Method patterns.

As I stated before, these are few ideas I wanted to use to spur discussions. In my opinion, it would be a good idea to have a TDD plan in place before we start creating engineering designs, which will likely happen next month.

Please provide me with your comments, suggestions, & ideas via email or in person (preferred). I would like to start these discussions in parallel with the creation of our use cases.

The Beginning & the End

How does a developer follow your specification?

We’ve all have been there.  Endless chains of code.  We have no idea of where it started and where it will stop.  You have that sense of being lost.  The problem is not necessarily with the size of the implementation, but with understanding the high-level steps through the code.  If you ever have found yourself in the debugger for hours try to locate that elusive defect within a massive code base, you know what I mean.

Often the approach to finding the code of interest is a process of elimination.  You ask yourself “Is this what I am looking for?”  You review it, and if it does not meet your criteria you move on to the next likely candidate.  If it met your criteria, you then drill down in to the code asking the same question over and over again until you discover what you are looking for.

This blind search eats up your time, it costs businesses money, and it delays efforts on other work products.

There are several techniques you can use to mitigate this problem:  refactoring, behavior-driven-development, etc.  I want to outline a technique when you are designing code for your system.  It involves informing the developer about the shortcuts s/he can take.

When you are presented the option to create software using a user stories or requirements, you often break down the problem in to its high level entities and their interactions.  For example, if you are building a payroll system and you need to write code to e-file paycheques you have several possible entities:  Employee, PayCheque, Aggregators for paycheques & employees, etc.  Once you identify them, you would relate each entity in the system to each other.  This effectively produces a logical representation of the problem domain you are trying to solve.

What it does not do is specify the flow of the user story or requirement through the system.  You could represent this in UML, but like documents, over time UML diagrams can get out of step with the code.  The problem of understanding flow may not seem relevant when you are the author and implicitly understand the intricacies of what you designed.  However when you move on to another project and someone needs to fix a defect in the code you wrote, the problem becomes apparent.

The next opportunity you have to design the representation of a user story or requirement, I would suggest that you design a class or method, that only delegates, where the entrance and exit of your specification is clearly outlined.

Imagine the following system:

class foo
{
    void Process()
    {
        // start the work
        DoMoreStuff();
    }
    
    void DoMoreStuff()
    {
        DoYetMoreStuff();
    }
    
    void DoYetMoreStuff()
    {
        FinishUpTheWork();
    }
    
    void FinishUpTheWork()
    {
        // finish up the work.
    }
}

Now imagine that you have a defect you need to find.  Where do you begin?  If you know the system, you may remember that Process() is where you need to start.  For someone who does not understand the system, they may start at DoYetMoreStuff() because that is where the defect happens to manifest.  If that person does not find the error there, s/he needs to follow the call stack to find the source.  In the above code, this is a very simple activity.  Now imagine a specification in your product that involves tens of classes and ten times more interactions between them.  The complexity of the problem increases greatly.  How fast do you think you would find the defect then if you had no current knowledge of the code?

Unit tests may help find the source of a defect, but not all changes are defects.  They may be enhancements to existing systems, or perhaps the developer needs to review some code in order to understand it.  Without a clear entrance or exit for the specification in your code, the developer is left to his own devices to find what s/he is looking for.

Compare the same code using a method that encapsulates the specification: 

class foo
{
    void Process()
    {
        // start the work
        DoMoreStuff();
        DoYetMoreStuff();
        DoYetMoreStuff();
        FinishUpTheWork();
    }
    
    void DoMoreStuff()
    {        
    }
    
    void DoYetMoreStuff()
    {        
    }
    
    void FinishUpTheWork()
    {
        // finish up the work.
    }
}

It is far easier for someone to start at Process() and eliminate components that do not need to be observed.  The benefits using this technique are:

1. A single entity is responsible for fulfilling the specification
2. It is easier to run automated tests to validate the specification
3. New developers can be directed towards a single point of entry and systematically eliminate entire sections of the process when locating functionality

I will be honest.  I do not think that this can be done in all cases.  Like many things in software development your coding standards, the condition of the existing code, your company’s best practices, and your experience all influence your designs.  I will state that this is an idea worth your time exploring the next time you create or edit code.

———-8<—————————————————–

How would you make a specification clear in your code?  Where does your specification begin and end?  Would this technique work for you?  an you leverage unit tests?  What about a combination of unit tests and this technique?

The ViewModel Distilled

A MVVM starter project for your consumption.

For the past few weeks, I have spending my evenings learning Silverlight 3.  It has been fun & insightful.  I had experience developing in Adobe Flex, so aside from the syntax it was a smooth transition.  One of the goals I had when I started was understanding how to leverage the ViewModel pattern in my applications.  ViewModel architecturally structures your code in a manner similar to the Model-View-Controller & Model-View-Presenter patterns.  The benefit of using ViewModel is that it capitalizes on the context (client applications) and features (data binding) of rich internet applications.  However learning the pattern was a bit frustrating.  There was a shortage of programmatic examples for implementing the ViewModel pattern in Silverlight.  I found a few for Silverlight 2, and fewer for version 3.

There were a few excellent & helpful resources:

Model-View-ViewModel In Silverlight 2 Apps

ViewModel Pattern in Silverlight using Behaviors

Using Model – View – ViewModel with Silverlight

These sources greatly helped my conceptual understanding & implementation of the ViewModel pattern.  However, each implemented the pattern in slightly different ways using different requirements.  Without a standardized implementation, the learning curve was longer than I expected.

I got through it though (yay!).  I managed to create a couple different applications using ViewModel.  After writing the third application though I was getting tired of recreating the same classes and directory structures.  What I needed was a template.  Something I could open when I needed it and start coding.  Most of the online sources I reviewed were very rich solutions so they did not lend themselves as ‘starter’ projects.  Others did not provide a complete project I could reuse.  So I opted to create my own ‘distilled’ version of the ViewModel pattern in Silverlight 3 using Microsoft’s Visual Web Developer 2008 Express Edition.  The application itself is very basic (it only displays an employee’s name).  But using this project as a template allows me to shave a few minutes of writing whenever I create a new ViewModel-based Silverlight application.

Feel free to download it and tweak it to your desires:

  http://cid-a537fc3c292692a7.skydrive.live.com/embedrow.aspx/.Public/MVVM|_Simple.zip

Some time after I created the template project, I stumbled upon the Silverlight Model-View-ViewModel Toolkit.  It is an open source project designed to solve the problems I was facing when I was learning ViewModel.  The toolkit is in its infancy, but worth the look if you are interested in learning about implementing ViewModel in Silverlight.