Ruthlessly Helpful

Stephen Ritchie's offerings of ruthlessly helpful .NET practices.

Visual Thinking and Communicating

The Periodic Table

Since a picture paints a thousand words, it makes sense that people communicate better with charts, graphs, and other visualization methods. The Periodic Table of Elements is a classic example of a great way to visualize atoms, their characteristics, and structural similarities. Anyone who has taken chemistry knows the significance of the diagram.

What are all your visualization options?

The site visual-literacy.org offers a compendium of visualization methods. One page shows a “periodic table” metaphor to help you access and sort out different visualization methods: A Periodic Table of Visualization

Some key things to note about the Periodic Table of Visualization Methods.

  • Hover over an element in the table and an example diagram is shown.
  • All the elements fall into categories, such as, data, strategy, and metaphor.
  • Some elements help to visualize processes while others visualize structure.

If you’re looking to present information, take some time to explore visual-literacy.org. There are a lot of great ideas, well illustrated on that site.

The Power of Free

A world-class education continues to become more affordable. The information is disseminating faster and at lower cost. Access to knowledge and new understanding is now mostly limited by your time, attitude and motivation.

MIT OpenCourseWare

MIT OpenCourseWare (MIT OCW) is an initiative of the Massachusetts Institute of Technology (MIT) to put all of the educational materials from its undergraduate- and graduate-level courses online, partly free and openly available to anyone, anywhere.

Source: From Wikipedia, the free encyclopedia (naturally)

This is a great way for people around the world to get a first-class education. Especially in the fields of engineering and science. However, I’m guessing an MIT degree still requires admission, matriculation, tuition, room, board, and other expenses. The learning is mostly free. The biggest investment seems to be your time.
For more information: http://ocw.mit.edu/index.htm

Caltech

The Machine Learning course, broadcast live from Caltech in April-May 2012.
http://work.caltech.edu/telecourse.html

There is an awesome trend happening. One that I believe will benefit all humankind.

How do you apply this to your software development projects?

Free Open Source ASP.NET Applications

The Microsoft ASP.NET site (http://www.asp.net) offers a lot of free educational and training material.

Look around. There are bunches and bunches of educational material offered free-of-change.

Added 3-May-2012

  • edX is a joint venture involving Harvard and MIT with the goal of improving the quality, effectiveness, and global reach of online university classes.

Added 13-Apr-2012

  • Udacity offers free online university classes for everyone.
  • Coursera.org offer courses from the top universities for free.

Build Numbering and Versioning

Build numbering is a topic filled with “political” and “cultural” significance. I mean that within organizations and among developers, we have heated debates over the numbering of software versions. Is this software 2.3 or 3.0? Or should it be 2.3.5.7919, 2.3.5.rc-1, or 2.3.5.beta?

Phil Haack recently offered some important information on Semantic Versioning (SemVer) specification and NuGet build numbering. Since the SemVer convention is a rational and meaningful way to version public APIs, it’s a good one to follow. Here are Phil’s posts:

The basics of SemVer: the version number has three parts, Major.Minor.Patch, which correspond to:
Major: Backwards incompatible changes
Minor: New features that are backwards compatible
Patch: Backwards compatible bug fixes only.

Everything after these three numbers is for a development organization to use, as it sees fit. Personally, I like ever-increasing, always-unique-for-a-major.minor-version integer numbers. Whether these are build numbers or revision numbers they can be managed by the build script or the continuous integration server.

However, build numbering and versioning has political and cultural significance and implications. Sadly, developers cannot always follow rational and meaningful numbering schemes.

Marketing

The Marketing Department of a commercial software company often wants to control the first two digits of the build number. They love to promote things like the company’s software is no longer version 2.3; now it’s 3.0! This change in major version generates interest and drives upgrade sales. In some cases, the software is a major new release, with significant new features. In other cases, it is just a marketing gimmick; there are only bug fixes and cosmetic changes in the new version.

Internally, developers hate it when Marketing overstates the major and minor version numbers of software. They feel that a minor release does not warrant an increment of the major version number. They want to follow systems like SemVer.

My opinion: As long as the numbers don’t violate the conventions of SemVer, let the major and minor version numbers belong to Marketing.

Marketing controls the product name. I have seen some crazy product name changes come from Sales and Marketing. As long as it isn’t too absurd, I go along with it. Why shouldn’t that be the same way with the major and minor version numbers? If Marketing wants 2.2 to be followed by 3.0, that’s OK with me. Going from 2.2 to 2.5 could represent a more accurate description of the perceived improvement. Either way, I don’t see it as my call. What I don’t like is jumping from 2.2 to 5.0 or regressing from 2.2 to 1.7, that’s absurd. The major version number should never increment by more than one. The combined major and minor number should always represent a decimal number greater than the prior version. Similarly, going from 2.2 to 2.3 must only introduce backwards compatible new features and backwards compatible bug fixes.

Bottom line, let Marketing own the major and minor version numbers. Insist that they follow the basic rules. Give them the guidance that increasing the major version number means “breaking changes are introduced”, “significant new features are added” or “it’s a total rewrite.” Minor version numbers are incremented when minor enhancements are added and bug fixes are made. Marketing must not break the paradigm. They are adults. If they are using sound judgement, let them own the major and minor numbers.

NuGet and the Nu World Order

In the .NET world, NuGet is very significant. With version 1.6, NuGet follows the SemVer specification. My current thinking on version numbering is that you ought to follow the version numbering that NuGet follows. The NuGet documentation describes the SemVer spec and what NuGet expects of version numbering.

Continuous Integration Server

The CI server is a great way to control and increment the version number.

Cruise Control .NET (CCNet) has the Assembly Version Labeller and TeamCity has the AssemblyInfo Patcher.

Incorporate this version numbering into your build script. Chapter 9 of Pro .NET Best Practices covers this topic. The free code samples are available at the bottom of the Apress page for the book, here.

Here is a good way to version assemblies: http://code.google.com/p/svnrevisionlabeller/

Ben Hall describes how to increment the build numbers with MSBuild and TeamCity: http://blog.benhall.me.uk/2008/06/team-city-update-assemblyinfo-with.html

Wikipedia, as usual, has a comprehensive entry on the topic of software versioning: http://en.wikipedia.org/wiki/Software_versioning

Keep Your Privates Private

Often I am asked variations on this question: Should I unit test private methods?

The Visual Studio Team Test blog describes the Publicize testing technique in Visual Studio as one way to unit test private methods. There are other methods.

As a rule of thumb: Do not unit test private methods.

Encapsulation

The concept of encapsulation means that a class’s internal state and behavior should remain “unpublished”. Any instance of that class is only manipulated through the exposed properties and methods.

The class “publishes” properties and methods by using the C# keywords: public, protected, and internal.

The one keyword that says “keep out” is private. Only the class itself needs to know about this property or method. Since any unit test ensures that the code works as intended, the idea of some outside code testing a private method is unconventional. A private method is not intended to be externally visible, even to test code.

However, the question goes deeper than unconventional. Is it unwise to unit test private methods?

Yes. It is unwise to unit test private methods.

Brittle Unit Tests

When you refactor the code-under-test, and the private methods are significantly changed, then the test code testing private methods must be refactored. This inhibits the refactoring of the class-under-test.

It should be straightforward to refactor a class when no public properties or methods are impacted. Private properties and methods, because they are not intended to be directly called, should be allowed to freely and easily change. A lot of test code that directly calls private members causes headaches.

Avoid testing the internal semantics of a class. It is the published semantics that you want to test.

Zombie Code

Some dead code is only kept alive by the test methods that call it.

If only the public interface is tested, private methods are only called thorough public-method test coverage. Any private method or branch within the private method that cannot be reached through test coverage is dead code. Private method testing short-circuits this analysis.

Yes, these are my views on what might be a hot topic to some. There are other arguments, pro and con, many of which are covered in this article: http://www.codeproject.com/Articles/9715/How-to-Test-Private-and-Protected-methods-in-NET

Fake 555 Telephone Number Prefix and More


Unless you want your automated tests to send a text message to one of your users, you ought to use a fake phone number. In the U.S., there is the “dummy” 555 phone exchange, often used for fictional phone numbers in the movies and television.

These fake phone numbers are very helpful. For example, use these fake numbers to test the data entry validation of telephone numbers through the user interface.

example.com, example.org, example.net, and example.edu

What about automated tests that verify email address validation? Try using firstname.lastname@example.com.

In all the testing that you do, select fake Internet data:

Fake URLs: http://www.example.com/default.aspx
Fake top-level domain (TLD) names: .test, .example, .invalid
Fake second-level domain names: example.com, example.org, example.net, example.edu
Fake host names: http://www.example.com, http://www.example.org, http://www.example.net, http://www.example.edu

Source: http://en.wikipedia.org/wiki/Example.com
Source: http://en.wikipedia.org/wiki/Top-level_domain#Reserved_domains

Fake Social Security Numbers

In the U.S., a Social Security number (SSN) is a nine-digit number issued to an individual by the Social Security Administration. Since the SSN is unique for every individual, it is personally identifiable information (PII), which warrants special handling. As a best practice, you do not want PII in your test data, scripts, or code.

There are special Social Security numbers which will never be allocated:

  • Numbers with all zeros in any digit group (000-##-####, ###-00-####, ###-##-0000).
  • Numbers of the form 666-##-####.
  • Numbers from 987-65-4320 to 987-65-4329 are reserved for use in advertisements.

For many, changing all the SSNs to use the 987-00-xxxx works great, where xxxx is the original last four digits of the SSN. If duplicate SSNs are an issue then use the 666 prefix or 000 prefix (or use sequential numbers for the center digit group) as a way to resolve duplicates.

Source: http://en.wikipedia.org/wiki/Social_security_number#Valid_SSNs

More Fake Data

There are tons of sources of fake data out on the Internet. Here is one such place to start your search:
http://www.quicktestingtips.com/tips/category/test-data/

Rules for Commenting Code

Unreadable code with comments is inadequate code with comments you cannot trust. Code that is well written rarely needs comments. Only comments that provide additional, necessary information are useful.

Yesterday a colleague of mine told me that he lost 10 points on a university assignment because he did not comment his code. Today I saw a photo with a list of rules for commenting attributed to Tim Ottinger.

Ottinger’s three rules make a lot of sense. These rules are straightforward. In my experience, they are correct and proper. Here are Ottinger’s Comment Rules:

1. Primary Rule

Comments are for things that cannot be expressed in code.

This is common sense. But, sadly, it is not common practice. Software is written in a programming language. A reader fluent in the programming language must understand the code. The code must be readable. It must clearly express what it is that the code does.

Only add comments when some important thing must be communicated to the reader, and that thing cannot be communicated by making the code any more readable. For example, a comment with a link to the MACRS depreciation method could be important because it helps explain the source of the algorithm.

2. Redundancy Rule

Comments which restate code must be deleted.

Any restatement of the code is unlikely to maintained over time. If the comment is maintained, then it just adds to the cost. More importantly, when comments are not maintained they either end up substantially misrepresenting the code or end up being ignored. Reading comments that misrepresent code is a waste of time, at best. At worst, they cause confusion or introduce bugs. Remove any comments that restate the code.

3. Single Truth Rule

If the comment says what the code could say, then the code must change to make the comment redundant.

Writing readable code is all about making sure that the compiler properly implements what the developer intended and making sure any competent developer can quickly and effectively understand the code. The code needs to do both: completely, correctly, and consistently. For example, a comment explaining that the variable x represents the principal amount of a loan violates the single truth rule. The variable ought to be named loanPrincipal. In this way the compiler uses the same variable to represent the same single true meaning that the human reader understands.

Tim Ottinger and Jeff Langr present more pragmatic guideance on when to write (and not write) comments: http://agileinaflash.blogspot.com/2009/04/rules-for-commenting.html

Now That’s High Praise

As a pragmatist, hearing that a fellow developer is getting a lot of value from my book is exhilarating. Dominic Zukiewicz wrote an excellent review of Pro .NET Best Practices. Here is the link to Dominic’s blog post: How to implement best practices with the .NET Framework

I’m a big fan of Steve McConnell. I’ve read most of his books and read Rapid Development cover to cover. I consider it his seminal work. It is very high praise to be compared favorably to Rapid Development.

Thank you.

Four Ways to Fake Time, Part 4

The is the fourth and final part in the Four Ways to Fake Time series. In Part 3 you learned how to use the IClock interface to improve testability. Using the IClock interface is very effective for new application development. However, when maintaining a legacy system adding a new parameter to a class constructor might be a strict no-no.

This part looks at how a mock isolation framework can help. The goal of isolation testing is to test the code-under-test in a way that is separate from dependencies and any underlying components or subsystems. This post looks at how to fake time using the product TypeMock Isolator.

Fake Time 4: Mock Isolation Framework

The primary benefit of a mock isolation framework is that no refactoring of the code-under-test is needed. In other words, you can test legacy code as it is, without having to improve its testability before writing maintainable test code. Here is the code-under-test:

using System;
using Lender.Slos.Utilities.Configuration;

namespace Lender.Slos.Financial
{
    public class ModificationWindow
    {
        private readonly IModificationWindowSettings _settings;

        public ModificationWindow(
            IModificationWindowSettings settings)
        {
            _settings = settings;
        }

        public bool Allowed()
        {
            var now = DateTime.Now;

            // Start date's month & day come from settings
            var startDate = new DateTime(
                now.Year, 
                _settings.StartMonth, 
                _settings.StartDay);

            // End date is 1 month after the start date
            var endDate = startDate.AddMonths(1);

            if (now >= startDate && 
                now < endDate)
            {
                return true;
            }

            return false;
        }
    }
}

With TypeMock, the magic happens in two ways. First, the test method arrangement uses the Isolate class to setup expectations. The test method sets up the DateTime.Now property so that it returns currentTime as its value. This fakes the Allowed method.
Here is the revised test code:

[TestCase(1)]
[TestCase(5)]
[TestCase(12)]
[Isolated] // This is a TypeMock attribute
public void Allowed_WhenCurrentDateIsInsideModificationWindow_ExpectTrue(
    int startMonth)
{
    // Arrange
    var settings = new Mock<IModificationWindowSettings>();
    settings
        .SetupGet(e => e.StartMonth)
        .Returns(startMonth);
    settings
        .SetupGet(e => e.StartDay)
        .Returns(1);

    var classUnderTest =
        new ModificationWindow(settings.Object);

    var currentTime = new DateTime(
        DateTime.Now.Year,
        startMonth,
        13);

    Isolate
        .WhenCalled(() => DateTime.Now)
        .WillReturn(currentTime); // Setup getter to return the test's clock

    // Act
    var result = classUnderTest.Allowed();

    // Assert
    Assert.AreEqual(true, result);
}

Second, the test must run in an isolated environment. This is how TypeMock fakes the behavior of System.DateTime; the test is running within the TypeMock environment. Here is the TypeMock Isolator configuration window.
TypeMock Isolator

The Cost of Isolation

Since TypeMock Isolator is a commercial product, be prepared to make the case for purchasing Typemock. Here is some information on the business case for TypeMock: http://www.typemock.com/typemock-newsletters/2011/3/7/typemock-newsletter-march-2011.html

I find that TypeMock Isolator 6.2.3.0 is well integrated with Visual Studio 2010 SP1, ReSharper 6.1 and dotCover 1.2.

In Chapter 2 of Pro .NET Best Practices, you learn about Microsoft Research and the Pex and Moles project. Moles is a Visual Studio power tool, and you will find the latest download through the Visual Studio Gallery. As I describe, the Moles framework allows Pex to test code in isolation so that Pex is able to automatically generate tests. Therefore, you can use Moles to write unit tests that fake time.

Moles, as a way to fake time, is described in the Channel 9 post Moles – Replace any .NET method with a delegate and the blog post Did you know Microsoft makes a mocking tool?.

Just like Code Contracts, I hope and expect that Microsoft will make Moles a more significant part of .NET and Visual Studio. Today, I don’t find that Moles offers the same level of integration (for now?) with ReSharper and dotCover that TypeMock has. When I use Moles, I run my test code within their isolation environment from the command line. It works, but I really do prefer using the ReSharper test runner.

To sum up the mock isolation framework approach:
Pros:

  • Works well when applied to legacy or Brownfield code
  • No impact on class-users and method-callers
  • A system-wide approach
  • Testability is greatly improved

Cons:

  • Tests must run within an isolation environment
  • Commercial isolation frameworks can be cost prohibitive

I hope you found this overview of four ways to fake time to be helpful. I certainly would appreciate hearing from you about any new, different, and hopefully better ways to fake time in coded testing.

Where’s CAT.NET 2.0?

If you go to the Microsoft Security Development Lifecycle implementation page, you read about performing static analysis with CAT.NET. If you follow one of the download links it takes you to CAT.NET v1 CTP.

About a year ago the Beta version of CAT.NET 2.0 was out from the Microsoft Security Tools team. It looked very promising. Today, I am having trouble finding the download for CAT.NET 2.0. The link on the team’s CAT.NET 2.0 – Beta blog post is broken.

There is very little information on the Information Security Tools team’s Connect site.

Does Microsoft have an update on the Security Development Lifecycle tools?

Four Ways to Fake Time, Part 3

In Part 2 of this four part series you learned how to use a class property to change the code’s dependency on the system clock to make the code easier to test. Adding the Now property is effective, however, adding a new property to every class isn’t always the best solution.

I don’t remember exactly when I first encountered the IClock interface. I do remember having to deal with the testability challenges of the system clock about 5 years ago. I was developing a scheduling module and needed to write tests that verified the code’s correctness. I think I learned about the IClock interface when I researched the MbUnit testing framework. At some point I read about IDateTime in Ben Hall’s blog or this article in ASP Alliance. I also read about FreezeClock in Ben’s post on xUnit.net extensions. Over time I collected the ideas and background that underlie this and similar approaches.

Fake Time 3: Inject The IClock Interface

I usually create a straightforward IClock interface within some utility or common assembly of the system. It becomes a low-level primitive of the system. In this post, I simplify the IClock interface just to keep the focus on the primary concept. Below I provide links to more detailed and elaborate designs. Without further ado, here is the basic IClock interface:

using System;

namespace Lender.Slos.Utilities.Clock
{
    public interface IClock
    {
        DateTime Now { get; }
    }
}

By using the IClock interface, the code in our example class is modified so that it has a dependency on the system clock through a new constructor parameter. Here is the rewritten code-under-test:

using System;
using Lender.Slos.Utilities.Clock;
using Lender.Slos.Utilities.Configuration;

namespace Lender.Slos.Financial
{
    public class ModificationWindow
    {
        private readonly IClock _clock;
        private readonly IModificationWindowSettings _settings;

        public ModificationWindow(
            IClock clock,
            IModificationWindowSettings settings)
        {
            _clock = clock;
            _settings = settings;
        }

        public bool Allowed()
        {
            var now = _clock.Now;

            // Start date's month & day come from settings
            var startDate = new DateTime(
                now.Year,
                _settings.StartMonth,
                _settings.StartDay);

            // End date is 1 month after the start date
            var endDate = startDate.AddMonths(1);

            if (now >= startDate &&
                now < endDate)
            {
                return true;
            }

            return false;
        }
    }
}

Under non-test circumstances, the SystemClock class, which implements the IClock interface, is passed through the constructor. A very simple SystemClock class looks like this:

using System;

namespace Lender.Slos.Utilities.Clock
{
    public class SystemClock : IClock
    {
        public DateTime Now
        {
            get { return DateTime.Now; }
        }
    }
}

For those of you who are using an IoC container, it should be clear how the appropriate implementation is injected into the constructor when this class is instantiated. I recommend you use constructor DI when using the IClock interface approach. For those following a Factory pattern, the factory class ought to supply a SystemClock instance when the factory method is called. If you’re not loosely coupling your dependencies (you ought to be) then you need to add another constructor that instantiates a new SystemClock, kind of like this:

public ModificationWindow(IModificationWindowSettings settings)
    : this(new SystemClock(), settings)
{
}

In this post, we are most concerned about improving the testability of the code-under-test. The revised test method sets up the IClock.Now property so as to return currentTime as its value. This, in effect, fakes the Allowed method, and establishes a known value for the system clock. Here is the revised test code:

[TestCase(1)]
[TestCase(5)]
[TestCase(12)]
public void Allowed_WhenCurrentDateIsInsideModificationWindow_ExpectTrue(
    int startMonth)
{
    // Arrange
    var settings = new Mock<IModificationWindowSettings>();
    settings
        .SetupGet(e => e.StartMonth)
        .Returns(startMonth);
    settings
        .SetupGet(e => e.StartDay)
        .Returns(1);

    var currentTime = new DateTime(
        DateTime.Now.Year,
        startMonth,
        13);

    var clock = new Mock<IClock>();
    clock
        .SetupGet(e => e.Now)
        .Returns(currentTime); // Setup getter to return the test's clock

    var classUnderTest = 
        new ModificationWindow(
            clock.Object,
            settings.Object);

    // Act
    var result = classUnderTest.Allowed();

    // Assert
    Assert.AreEqual(true, result);
}

If you’re looking for more depth and detail, take a look at this very good post on the IClock interface by Al Gonzalez: http://algonzalez.tumblr.com/post/679028234/iclock-a-test-friendly-alternative-to-datetime

The Gallio/MbUnit testing framework has its own IClock interface. I don’t like production deployments containing testing framework assemblies; however, the Gallio approach offers a few ideas to enhance the IClock interface.

Pros:

  • Works well with an IoC Container/Dependency Injection approach
  • Can work with .NET Framework 2.0 and later
  • No impact on class-users and method-callers
  • A system-wide approach
  • Testability is greatly improved

Cons:

  • System-wide change, some risk
  • Can be disruptive when applied to legacy or Brownfield applications

I often use this approach when working in Greenfield application development or when major refactoring is warranted.

In the next part of this Fake Time series we’ll look at a mock isolation framework approach.

Follow

Get every new post delivered to your Inbox.