Coding Practices and Design Patterns

How to Reuse Code Without Creating an Implicit API

Chris Falter — Sun, 29 Mar 2009 19:44:23 GMT

I work for an ISV, and we have to be very cautious about the code that we declare with public scope. If it's public, a customer can treat it as an API, which might not always be a good idea if the code is really just doing some internal task in a way that could easily change as we improve our software. In other words, not all that is public should be an API.

So what do you do if you need to share code across assembly boundaries? Recently I was writing some unit tests for a class, and the tests needed access to a class method in order to imitate (and test) its behavior. Of course this method was private--of course!--so it appeared that I had to choose between 2 very unpalatable options:

Give the method public scope, which would make it visible to all our customers' implementations. Essentially, this option would make the method part of our API. Not happening.
Copy the 20 lines of code from the method, paste it into my new class, and supplicate the dark spirits of bad software design to supernaturally prevent the method from ever being modified. But how could I perform the ritual without an eye of newt and toe of frog?*

But appearances can be deceiving. It turns out that the InternalsVisibleToAttribute, introduced by Microsoft in .NET 2.0, solves the problem quite neatly. Using this attribute, you can designate one or more friend assemblies that will be allowed access to classes, methods and properties in the target assembly that have friend scope, while all other code--including customer code--is denied access.

Using the attribute is a piece of cake:

Mark any classes/methods/properties that need to be visible to other assemblies with "Friend" scope.
Import the System.Runtime.CompilerServices namespace into your assembly's AssemblyInfo.vb file.

Imports System.Runtime.InteropServices
In AssemblyInfo.vb, mark the assembly with the InternalsVisibleToAttribute for each friend assembly that should have access to the friend scope.

<Assembly: InternalsVisibleTo("MySystem.Assembly1")>
<Assembly: InternalsVisibleTo("MySystem.Assembly2")>

If you are working in C#, you will make your changes in the AssemblyInfo.cs file for the assembly that contains the code to be re-used, and you will use "using" instead of "Imports."

So I could have my cake (re-use of existing code) and shield it from inappropriate eyes at the same time. While this technique is obviously useful for writing tests, it can be applied anywhere that code needs to be shared between your system's assemblies without exposing it customers as part of an API.

* Not to mention the wool of bat and tongue of dog.

How To Create a Windows Form Singleton

Chris Falter — Fri, 06 Jun 2008 14:31:25 GMT

Recently a friend asked me how you might create a Windows Forms application that only allows a single instance per computer. A print driver might make use of this functionality, for example, to launch a print job management dialog whenever a document prints. Never having needed this sort of functionality before, my initial answer wasn't very helpful. But being both curious and disinclined to back down from a technical challenge, I just had to figure this one out.

As I was looking for an inter-process synchronization mechanism, I came across the Semaphore and Mutex in the System.Threading namespace. A semaphore can be used to manage a pooled resource (memory buffer, thread pool, connection pool, etc.) by tracking the number of available resources. You instantiate a semaphore with an invariant maximum corresponding to the quantity of pooled resource entities (e.g., the number of database connections). Whenever a thread wants to use the resource, it calls .WaitOne() on the appropriate semaphore and blocks until the semaphore count is greater than zero. If the count is positive when the call is made, the thread will not need to block at all.

When a thread enters a semaphore, the semaphore decrements its count by one. The calling thread is responsible for calling the semaphore's .Release() method when it has completed using the resource. This allows the semaphore to increment its count--and as a result, gives another thread access to the pooled resource. You must call Release() inside of a finally block as soon as feasible in your codepath; my testing shows that the CLR will not release an unreleased semaphore when the semaphore reference goes out of scope, or even when the thread of execution terminates.

What we need, then, is a semaphore that has a maximum count of one (since we want only one instance of our application to be running) and will increment its count no matter how the thread that entered it terminates. Happily, this would be a pretty good one-sentence description of the Mutex class. The thread that calls WaitOne on a mutex ("mutual exclusion") gains ownership when it enters the mutex. It can release the mutex at any time by calling the ReleaseMutex method, but should it fail to do so (whether by logic error or run-time failure) before it terminates, the CLR will release the mutex on its behalf. As a result, the mutex should prove more reliable for our purposes.

Here is the singleton code in a nutshell:

using System;

using System.Windows.Forms;

using System.Threading;

namespace MutexTest

{

    static class Program

    {

        [STAThread]

        static void Main()

        {

            Application.EnableVisualStyles();

            Application.SetCompatibleTextRenderingDefault(false);

            // make sure no other instances of this app are running

            bool mutexIsAvailable = false;

            Mutex m = null;

            try

            {

                m = new Mutex(true, "MutexTest.Singleton");

                mutexIsAvailable = m.WaitOne(1, false); // wait only 1 ms

            }

            catch (AbandonedMutexException)

            {

                // don't worry about the abandonment; 

                // the mutex only guards app instantiation

                mutexIsAvailable = true;

            }

            if (mutexIsAvailable)

            {

                try

                {

                    Application.Run(new Form1());

                }

                finally

                {

                    m.ReleaseMutex();

                }

            }

        }

    }

}

One of three things can happen when the Main() thread calls m.WaitOne(1, false):

If the mutex is unowned (or becomes unowned within one millisecond), mutexIsAvailable is true and the thread enters/owns the mutex.
If the mutex remains owned by another instance of the Windows Form app for the one millisecond duration, mutexIsAvailable is false.
If the mutex is available because another instance abandoned it without releasing it, the method throws an AbandonedMutexException. In this case, the thread owns the mutex and may safely launch the application instance, so it sets mutexIsAvailable true.

If the Main thread owns the mutex, it runs the application, using a try/finally block in order to guarantee a call to ReleaseMutex. While strictly speaking it is not necessary to call ReleaseMutex (the CLR will do so on the thread's behalf when it terminates), I have written the code this way in order to maintain a best practice. In some other situation, the thread that enters the mutex might continue performing more work (or enter a suspended state) after finishing its use of the resource and might not call ReleaseMutex, so it's a good idea to write the code in this fashion.

What do you think? Is this code helpful? Do you have any suggestions for improvement? Leave a comment!

BOOK REVIEW: Don't Make Me Think, 2d Ed. by Steve Krug

Chris Falter — Tue, 13 May 2008 20:31:39 GMT

You've mastered web forms and controls. You've prototyped a Silverlight 2.0 application. AJAX? You're all over it. But have you really learned how to design a good web page or web site?

Steve Krug's "Common Sense Approach to Web Usability" provides surprising and sometimes counterintuitive principles that every good website must follow. Krug preaches the importance of removing clutter in order to make the purpose and functionality of a site (or page) clear--and happily, he practices what he preaches in this remarkably lucid book. Here are some of Krug's key insights:

Don't make users think! Your job is to make sure users do not have to puzzle over a site's purpose, or how to use it. Krug offers the search functionality at Amazon.com as a great example of this principle in action. A user does not have to decide what type of search she wants (by author, by title, by ISBN, etc.); instead, she can just enter whatever text interests her, and Amazon offers a list of matches, ranked by relevance.
Users don't behave the way you think they do. You've been poring over your site--reading everything ten times or more--so you tend to think that users will do the same. But they don't. Instead, the users...
- "don't read pages, they scan them." (In fact you only decided to read this review after you scanned the intro and decided it would be worth your while.)
- "don't figure out how things work, they muddle through."
Design pages for scanning. Since users are going to treat your site like a billboard going by at 70mph (rather than a textbook that they carefully work through), you should learn to design great billboards!
- Create a clear visual hierarchy. Highlight the important stuff, and indicate relationship by grouping.
- Use conventions. If your site design conforms to what users generally expect, they can more easily understand it at a glance.
- Break pages into clearly defined areas.
- Make what's clickable obvious. Use arrows or underlines to indicate that text is clickable, for example.
- Minimize noise. Prefer clarity to pizzazz.
Give users simple\mindless choices. It's okay to make a user traverse 4 or 5 links to get to his desired destination as long as each choice along the way is clear.
"Omit needless words." "Get rid of half the words on each page, then get rid of half of what's left" is Krug's Third Law of Usability. More words just make the site look more daunting, which can discourage the user in a hurry. Krug's Third Law has 2 corollaries:
- Happy talk must die. "We're so glad you're at our site! We think you'll like your experience here..." Oops, you just lost your user, who's too busy to keep reading.
- Instructions must die. Users almost never read them anyway (remember, they don't figure out, they muddle through). So keep instructions brief and simple.

Krug then discusses some details about 2 features every site must have: navigation and a home page. Krug recommends that the sections and subsections of a site be indicated with a clear set of links or tabs on the home page, and that the navigation remain available no matter where the user goes. (This answers the questions: what can I do on this site? and Where can I go from here?) Each page should have a visible name, and the site should a breadcrumb trail with arrows between the levels in order to allow a user to know where he's at in the site's hierarchy. (These answer the questions: where am I at now? and How do I get back to where I was before?).

Krug's discussion of the home page acknowledges that the forces conspiring against simplicity are enormous in any ambitious site, because there are so many organizational interests competing for the valuable home page real estate. Krug provides some useful tips for managing the problems, though, by suggesting how to use logos, taglines, and home page navigation.

Next Krug addresses the often religious arguments that site development teams often endure (pulldowns or menus? Flash animation or simple text?) with this simple advice: forget the arguments and start testing! Simple usability testing will reveal the key problems with a site, and often they have nothing to do with what the development team has been arguing about. Krug believes that frequent tests are more important than comprehensive (often expensive tests), and he offers advice on how to do testing on a tight budget (use 3 or 4 subjects; use an inexpensive screen recorder like Camtasia; try to get all the project stakeholders to observe). He concludes with an extremely useful script of an interaction between a test subject and a test guide.

Those who have already read the first edition will be pleased to know that Krug has included some very helpful new material in the second edition. Is your site accessible to sight-impaired users? If not, Krug offers a top 5 list of tips for making sites accessible, along with a pointer on how to use Cascading Style Sheets to make your site more accessible. Not to mention that CSS makes your site a lot easier to manage.... And what do you do when your boss (or the customer) wants you to do something that violates every known law of web usability? Just compose an email that borrows liberally from one of Krug's friendly "here's how it should be done" missives!

Krug sprinkles his book with examples of sites that work well (and a few that don't) to illustrate his ideas. He often offers a few "How does (or does not) this page implement the principles we've been discussing?" tests, with his own answers on the following pages. I found these examples to be enormously helpful. And Krug offers a wonderful set of additional resources for those who want to pursue the subject further, both within the text and in a notated bibliography at the end.

Because I am a long-time web user and web developer, I thought I understood just about everything I needed to know about usability to design a good site. Then I read this book, and learned a ton. If you work on web sites in any way (whether as designer, developer, or tester), the few hours you spend on Steve Krug's little gem will pay rich dividends.

Want to Write Great Business Software? Create a Great Domain Model!

Chris Falter — Tue, 25 Mar 2008 14:01:28 GMT

When you are coding in a hurry, it is very tempting to write business logic in the first place that comes to mind, such as a button click handler. However, for all but the simplest systems, such a practice leads very quickly to a chaotic system whose business logic is scattered like the ash from an erupting volcano. So let's take a step back and see how you can develop an application more intelligently.

"Divide and Conquer"

“Divide and Conquer” is a useful metaphor for organizing the effort of developing a complex system. A software architect can assign major system responsibilities to various components or layers (which I will refer to as a “part”). As long as the responsibilities of a part are understood, a developer can develop the part in such a way as to satisfy those responsibilities. And as long as the parts integrate well, a useful system can emerge.

“Divide and Conquer” has many advantages:

A team can work in a coordinated fashion on several parts of the system simultaneously, without stepping on each other’s toes.
Assigning a limited set of related responsibilities to a system part simplifies its design.
Modifying a system is easier when the part that is responsible for the functionality that must be changed can be identified.
Ultimately, the complexity of the system decreases as its various responsibilities, and the strategies for handling them, become clear. Unnecessary complexity is what can make “the last 10%” of a project go into deep cost and time overruns, as quality issues and poor design make their effects known.

“Divide and Conquer” is the driving force behind creating logical layers of a user interface, an application layer, a data layer, and a domain model in an enterprise software application.

While the advantages of separating UI, application, and data logic into their own layers are well understood and frequently practiced, the point behind creating a domain model is not as widely grasped. A domain model defines the business entities represented by a system, the activities associated with them, the relationships between them, and the rules and constraints that govern them. These are clearly very important aspects of the system, even though (from the end user’s perspective) they are not as visible as the user interface, application flow, or database. I will illustrate the importance of a domain model by examining how insurance endorsements work in the homeowners point-of-sale system that my team has developed.

Example of a Complex Business Domain

Let’s start by examining the data model for endorsements:

An endorsement can be associated with either an application (future policy) or with a risk (such as a dwelling or a vehicle). Therefore the Endorsement table has 2 foreign keys: one that relates an endorsement to an application (via the Quotenumber) and the other that relates it to a risk (via the RiskId).
Endorsements come in a bewildering variety. Some endorsements have no related data; some have one or more limits; some have one or more attributes, few of which are common between endorsements. Clearly it is unwise to attempt to create a single table with identified columns for each of the possible limits or attributes that an endorsement may possess. In addition, any attempt to create a unique table for each endorsement’s associated attributes is going to result in a very large number of tables—along with the responsibility of defining a new table each time a new endorsement type is created. Therefore, the design we chose was to create 2 dependent tables for Endorsement: an EndorsementLimit table and an EndorsementDescription table. Each table has 3 fields: an EndorsementId (foreign key back to the associated endorsement), a “type” field that allows the system to distinguish between all the related descriptions (or limits) of an endorsement, and the associated data field (a numerical limit or a varchar description). Note that segmentation and history are irrelevant to a point-of-sale system, so the schema is not designed with that capability.
Some endorsements are concerned with parties to an insurance application other than the applicant, such as an additional interest or an additional insured. Since these additional entities reside in a different table (the OtherParty table), we use a join table (EndorsementParty) to manage the association between Endorsement and OtherParty.

This portion of the database schema is represented graphically below:

So if we have a data model, why do we need a domain model? Why can’t some UI code simply write its data directly to the tables? Clearly this one way of designing a system—you can, after all, do anything with software (provided you have sufficient time and resources).

Let us consider, though, the knowledge about the business domain that the point-of-sale application must manage with regard to endorsements:

The relationship of endorsement attributes to an endorsement. A homeowners “HO 05 28” (golf cart) endorsement has several related attributes: a limit (cart value), a make, a model, a serial number, and an indicator of whether collision coverage is included. Each one of these attributes is stored in its own record in the EndorsementLimit or EndorsementDesc table. The DescType field distinguishes the four EndorsementDesc records from one another; however, the system must somehow keep track of which DescType is used for which attribute.
Differences between the format of stored data and how it is used. In a database system that does not have a built-in boolean type (such as the DB2 flavor used at my shop), there are probably as many different ways to store boolean data as there are programmers. True vs. false could be represented as “0” vs. “1”, or as “1” vs. “2”, or as “T” vs. “F”, or as “t” vs. “f”, or as “true” vs. “false”, or as “Y” vs. “N”, etc. (In one of my consulting engagements, I actually saw all of these plus a couple more in a single application.) To handle a golf cart endorsement’s indicator of collision coverage, the system must be able to reliably map between the stored data and a run-time choice of true/false.
The relationships between endorsements and other entities. Some endorsements are related to the risk being insured (such as the earthquake endorsement), and some are related to the (potential) policy itself (such as an “Additional Insured” endorsement).
The relationships between endorsement attributes. The “HO 04 65” endorsement (scheduled property) contains a set of schedules; each schedule is designated by a letter such as “A” or “J” and has a description (the personal property being insured) and a limit. Since descriptions and limits are stored in separate tables, the system must have some way of identifying and associating the schedules’ descriptions and limits.
Rules and constraints on various endorsements. The 6 schedules on a “HO 04 65” endorsement have base (default) limits, for example, such that the total limit of a schedule can be described as the base limit plus an additional limit. Mathematically speaking, we use the formula Total Limit = Base (fixed by rule) + Additional (stored in EndorsementLimit table). So the system must be able both to provide base, additional, and total limits (given the stored additional limit) and to update the stored additional limit (based on user entry).

Complexity Resolved: A Domain Model

The beauty of our team's domain model is that it completely hides all of this complexity from the user interface.

An endorsement class is defined for each type of endorsement, and it provides an interface that is radically simple for the UI developer to use. To give just one example, the golf cart endorsement provides a boolean CollisionIncluded property that can be mapped to a checkbox.
All of the other issues (which EndorsementDesc record the indicator is stored in, how the boolean is mapped to a varchar, etc.) are managed inside an endorsement class—frequently by using capabilities inherited from the EndorsementBase class or borrowed from utility classes in the domain layer.
Responsibilities are clearly grouped and assigned in this way of designing a system. Tasks and attributes that are common to all endorsements are the responsibility of the EndorsementBase class. The tasks and attributes that are unique to a particular endorsement are the responsibility of the corresponding subclass of EndorsementBase (which already has the common endorsement capabilities via its inheritance relationship with EndorsementBase). Neither of these classes needs to know anything about the application or user interface which will use them, which in turn need to know nothing at all about the internal implementation details of an endorsement class. The diagram below depicts the assignment of some endorsement responsibilities to classes in our domain layer.
The association of an endorsement with a policy or with a risk is managed via its membership in an EndorsementCollection that is accessed via the HomeApplication object or the HomeApplication.Home object (of type HomeRisk), respectively. The relationship between these various entities is depicted below.

Conclusion

There are some things that should never leak. Space shuttle O-rings. Tires. Diapers. And now that you've read this article, add your business domain model to the list. Always isolate your business domain logic in a cohesive model; do not let the logic leak into a "smart UI" or into the data layer! If you follow this rule, you will save yourself and your team much time and effort when you need to modify the business logic in your application.

Also, keep the importance of your domain model in mind when it is time to choose a development tool. A rapid application development (RAD) tool that can only design screens and logic flows might be a very good choice for building a very simple system that needs little complexity in its business logic. However, it is very difficult to envision how a RAD tool would be able to represent the relationships and constraints inherent to a complex business domain, such as homeowners insurance endorsements. Given the inherent limitations of a RAD tool, the complexity that my team's domain model currently manages quite capably would have to spill out into the flows and screens themselves.

While the result may initially seem counterintuitive, a RAD tool that at first glance makes everything look simple might very well in the end produce a system far more complex than a system produced with a set of tools that offer a robust and complete set of programming capabilities. And this unanticipated complexity can make the systems you develop far more difficult to implement on time and to extend with new customer-requested capabilities.

Refactoring to Comply with the DRY principle (Don't Repeat Yourself)

Chris Falter — Fri, 07 Mar 2008 13:45:40 GMT

If you're not living DRY, you're not a good programmer.

Okay, I'm not talking about alcohol consumption! I'm talking about the Don't Repeat Yourself principle--a principle every programmer should live by. Recently I did a code review for a project we outsourced, and demonstrated how you can refactor bad cut-and-paste code into well-designed code. You will note that the capabilities of the MagicStringTranslator class really help to reduce code clutter. Without further ado, I present the relevant portion of my code review:

...your branching logic has 12 lines of code in each branch except the final one. I am inserting an excerpt for reference:

if (m_record.Text.Substring(13, 6).Trim() == "IDENT")

{

writer.WriteBreak();

writer.WriteFullBeginTag("Table style='width: 100%' border='1'");

writer.WriteFullBeginTag("tr style='background-color:#ccffcc;'");

writer.WriteFullBeginTag("td style='width: 100%;' colspan='2' align='center'");

writer.WriteFullBeginTag("span style='font-size: 9pt;");

writer.WriteFullBeginTag("strong");

writer.Write("SUBJECT INFORMATION");

writer.WriteEndTag("strong");

writer.WriteEndTag("span");

writer.WriteEndTag("TD");

writer.WriteEndTag("TR");

writer.WriteEndTag("Table");

}

if (m_record.Text.Substring(13, 6).Trim() == "SUMRY")

{

writer.WriteBreak();

writer.WriteFullBeginTag("Table style='width: 100%' border='1'");

writer.WriteFullBeginTag("tr style='background-color:#ccffcc;'");

writer.WriteFullBeginTag("td style='width: 100%;' colspan='2' align='center'");

writer.WriteFullBeginTag("span style='font-size: 9pt;");

writer.WriteFullBeginTag("strong");

writer.Write("SUMMARY");

writer.WriteEndTag("strong");

writer.WriteEndTag("span");

writer.WriteEndTag("TD");

writer.WriteEndTag("TR");

writer.WriteEndTag("Table");

}

if (m_record.Text.Substring(13, 6).Trim() == "COLLT")

{

// this code and several more near-identical branches are omitted for brevity’s sake

}

Eleven of these lines of code are identical. This is bad for 3 reasons:

What would happen if one of the lines of code had a bug? You would have to fix it in each branch, and be sure to do it the same way in each one. This code structure is bug-prone.
The structure implies that each branch does different things, when the code in fact does essentially the same thing. As a result, the code structure is misleading.
The code ends up being way too verbose; it is saying the same thing over and over and over. As a result, the code structure is hard to read and understand.

In fact, your code does suffer from an insidious little bug. You are comparing a substring of length 6 to a literal of length 5.

if (m_record.Text.Substring(13, 6).Trim() == "IDENT")

This only happens to work when the 6th character is a blank, because in this circumstance the Trim() method reduces the string to length 5, and the comparison is valid. What would happen if the 6th character did not happen to be a blank?

But don't try to fix this bug in the seven places where it occurs! There are better ways to improve the code. One way is to restrict the branching logic to the one line of code, then use that one line together with the other 11 exactly once.

string title = String.Empty;

switch (m_record.Identifier)

{

case "IDENT":

title = "SUBJECT INFORMATION";

break;

case "SUMRY":

title = "SUMMARY";

break;

case "COLLT":

title = "COLLECTION ITEMS";

break;

case "ACCNT":

title = "TRADE ACCOUNT ACTIVITY";

break;

case "MSSGE":

title = "MESSAGE";

break;

case "EMPLY":

title = "EMPLOYMENT";

break;

case "INQHS":

title = "INQUIRY HISTORY";

break;

}

writer.WriteFullBeginTag("Table style='width: 100%' border='1'");

writer.WriteFullBeginTag("tr style='background-color:#ccffcc;'");

writer.WriteFullBeginTag("td style='width: 100%;' colspan='2' align='center'");

writer.WriteFullBeginTag("span style='font-size: 9pt;");

writer.WriteFullBeginTag("strong");

writer.Write(title);

writer.WriteEndTag("strong");

writer.WriteEndTag("span");

writer.WriteEndTag("TD");

writer.WriteEndTag("TR");

writer.WriteEndTag("Table");

An even better way is to delegate the relationship between magic string (e.g., “INQHS”) and description (e.g., “INQUIRY HISTORY”) to a class specialized for this purpose. Then you can simply use the class directly, without writing any branching logic at all. In this situation, define a MagicStringTranslator subclass for the Identifier property:

public class IdentifierCode : MagicStringTranslator

{

public const string SUBJECT_INFO = "IDENT";

public const string SUMMARY = "SUMMARY";

public const string COLLECTION_ITEMS = "COLLT";

public const string TRADE_ACCOUNT_ACTIVITY = "ACCNT";

public const string MESSAGE = "MSSGE";

public const string EMPLOYMENT = "EMPLY";

public const string INQUIRY_HISTORY = "INQHS";

}

Then make the class’ Identifier property of type IdentifierCode:

public IdentifierCode Identifier

{

get{ return new IdentifierCode(segments[(int)Fields.Identifier].Data); }

set { } // no-op setter provided so that XmlSerializer can serialize this property

}

Finally, use the Identifier directly, without any need for branching logic:

writer.WriteFullBeginTag("Table style='width: 100%' border='1'");

writer.WriteFullBeginTag("tr style='background-color:#ccffcc;'");

writer.WriteFullBeginTag("td style='width: 100%;' colspan='2' align='center'");

writer.WriteFullBeginTag("span style='font-size: 9pt;");

writer.WriteFullBeginTag("strong");

writer.Write(m_record.Identifier.Description);

writer.WriteEndTag("strong");

writer.WriteEndTag("span");

writer.WriteEndTag("TD");

writer.WriteEndTag("TR");

writer.WriteEndTag("Table");

And you're done.

A Good Solution for "Magic String" Data

Chris Falter — Thu, 06 Mar 2008 16:08:45 GMT

Dealing with vendor data (or your own) in the form of "codes" can pose significant challenges. You must ensure that your source code remains readable, that data are properly validated, and that data can be displayed as user-friendly descriptions. The built-in solutions (named constants and enums) help, but they have some significant shortcomings. If you derive a class of named constants from the MagicStringTranslator class, though, you can vanquish all 3 challenges in one fell swoop!

Egghead Cafe has kindly published the improved version of my article here. Enjoy!

Make Magic Strings Easy to Understand and Type Safe

Chris Falter — Wed, 27 Feb 2008 07:40:16 GMT

As organizations pass data back and forth, they often use codes to represent the data. For example, a marital status of divorced might be represented as "D", married as "M", and so forth. You have to solve three problems when you are dealing with magic strings:

When you write logic to handle the data, things can get chaotic on a hurry if you are not careful; the use of literal magic strings in your source code can make it incomprehensible.
You can get into trouble by passing a string that is not in the set of valid codes as a parameter to a method that is expecting one of the codes. Since the parameter type is typically string, the compiler will not help you detect the error.
You often have to translate codes into it description so a user of your system will know which data have been gathered.

Using named constants can help make your source code more readable, but you still have more work to do: you must write extra logic to check whether a string belongs to the set of valid codes, and to translate a code into a description that a user can understand. If you declare your named constants in a class that inherits from the MagicStringTranslator class, though, you will get the data validation and the translation for free. Check out the article I wrote for the details!

"New" Statement Considered Harmful

Chris Falter — Fri, 15 Feb 2008 20:59:48 GMT

All of us have probably written code like this:

Foo f = new Foo();

And what could be simpler? As long as the logic in the constructor is simple (or better yet, the constructor is empty), it would seem that the simplest code is the best, so just use the constructor. Certainly the MSDN documentation is rife with code that uses public constructors. You can probably find plenty of public constructors used right here on my blog. Why invest the effort in writing (and using) a factory class that will probably never do anything useful, other than call a public constructor?

In his excellent podcast entitled "Emergent Design: The Evolutionary Nature of Software Development," Scott Bain of Net Objectives nevertheless makes a strong case against the routine use of public constructors. The problem, notes Scott, is that the use of a public constructor ties the calling code to the implementation of Foo as a concrete class. But suppose that you later discover that there need to be many subtypes of Foo, and Foo should therefore be an abstract class instead of a concrete class--what then? You've got a big problem, that's what; a lot of client code that has been making use of Foo's public constructor suddenly becomes invalid.

Exposing a public constructor, observes Bain, allows code to violate the open/closed principle. This principle states that software should be open for extension, but closed for modification. Restating this in more mundane terms, developers should design their code in such a way that extending it (for example, making a class more useful by defining it as abstract and subclassing it as appropriate) does not provoke side effects elsewhere--and that's the "closed for modification" part in a nutshell.

Bain points out that there is a simple, low-cost practice that avoids the public constructor's violation of the open/closed principle. Just give a class constructor protected scope, and define a static Create method that uses the constructor--that's it. Here's class Foo's new skeletal definition in C#:

public class Foo
{
protected Foo() {}

public static Foo Create() { return new Foo(); }
}

How hard was that? At the cost of a single line of code, you get benefits well beyond the already mentioned ability to transform the class into an abstract base class:

If object construction becomes more complex, you can use a factory class inside the Create method.
You can implement the Dependency Injection pattern, which facilitates unit testing with mock objects.
You can use Microsoft's Policy Injection Application Block to implement cross-cutting concerns such as logging, authorization, and validation.

Unfortunately, you may occasionally encounter a corner case where you must define a public constructor. The .NET Framework's XmlSerializer cannot be used on a class with no public default constructor, since XmlSerializer must instantiate the class in order to discover the public properties that must be serialized. If you plan to serialize a class using XmlSerializer, then, you must make the constructor public--but you should mark it with the ObsoleteAttribute to warn fellow developers not to use it:

public class Foo
{
[Obsolete("Do not use--provided only for use by XmlSerializer. Client code should call Foo.Create().")]
public Foo() {}

public static Foo Create() { return new Foo(); }
}

If due to habit a fellow programmer calls the public constructor (against your intentions), the C# compiler will emit a helpful warning message. Of course, there are programmers who ignore warnings, but that is the subject of a different post.

Of Sobriety Tests and Loop Iteration

Chris Falter — Thu, 08 Nov 2007 11:44:40 GMT

A few years ago I listened in fascination to a radio interview with a highway patrol officer who was describing how she conducted field sobriety tests. In addition to the typical tests of walking in a straight line and of standing on one foot, she would ask the erratic driver to recite the alphabet. One driver slurred, "A. Is that good enough?" "That's all the alphabet you can recite?" she responded. "Yep," he answered. She booked him. She would also ask drivers to count backwards from 100. If a driver skipped around or had to think hard, his mental facilities were not sharp enough to permit him to drive safely.

Counting backwards can also come in handy when you're performing a loop iteration. For years we had some data access code that looped through a DataRowCollection in order to commit changes to a DB2 database:

public void SaveRows(DataTable tbl)

{

    string spName = null;

    for (int i = 0; i < tbl.Rows.Count; i++)

    {

        DataRow row = tbl.Rows[i];

        DataRowState rowState = row.RowState;

        if ((rowState & DataRowState.Unchanged) > 0)

            continue;

        switch (row.RowState)

        {

            case DataRowState.Added:

                spName = "SPI" + tbl.TableName;

                break;

            case DataRowState.Modified:

                spName = "SPU" + tbl.TableName;

                break;

            case DataRowState.Deleted:

                spName = "SPD" + tbl.TableName;

                break;

        }

        try

        {

            IDbDataParameter[] parms = DataHelperParameterCache.GetSpParameterSet(DataHelper.ConnectionString, spName);

            CallStoredProc(spName, parms, row);

        }

        catch (Exception ex)

        {

            if (tx != null)

            {

                tx.Rollback();

                rolledBack = true;

            }

            throw new BaseApplicationException("Fatal Exception while running stored proc " + spName, ex);

        }

    }

}

Then after we had called this function on all the DataTables in the DataSet, we called DataSet.AcceptChanges(). This code generally worked well.

Then one day we realized that by not using a IDbTransaction (we left it null) and calling DataSet.AcceptChanges() at the end, we would leave our DataSet in a state inconsistent with the data store if a failure occurred part way through the process of saving tables and rows. For example, if a row had been inserted to the data store, but AcceptChanges() had not been called, then its RowState was still DataRowState.Added. And the next time a user tried to save his work, our system would try to insert an additional row, rather than updating the row that was already in the data store. So we decided to call DataRow.AcceptChanges() after each row operation (after the call to CallStoredProc in the above code).

A few days later, our testers reported that the last of 2 delete operations would no longer commit to the data store. What? How could adopting a new strategy for accepting changes cause that kind of bug?

Well, what happens when you call DataRow.AcceptChanges() when the RowState is DataRowState.Deleted? Poof! It vanishes into thin air. As a result, the next row would get skipped over in the loop iteration, since its ordinal had shifted back by one.

Allow me to illustrate: you've got 2 rows, and you're going through the loop. The first time you enter the loop body, i is 0 and you're working with Rows[0], the first row. Before you finish the loop, you call DataRow.AcceptChanges(), and the row disappears in a cloud of smoke, alakazam! Now the row that used to be at Rows[1] shifts back to Rows[0], and Rows.Count == 1. And we're at the end the loop, so we increment i to 1 and do the test:

i < tbl.Rows.Count

This statement is false, so we exit the for loop. Thus the row that shifted from index 1 to index 0 (when its sibling vanished) never got processed.

My first thought on fixing the problem was to use a foreach loop and let it figure out how to deal with the deletion for me. However, the DataRowCollection quite correctly threw an InvalidOperationException when we tried it, and I can't blame the class designers for the behavior. Remember, the iterator is supposed to keep track of the Current and the Next member of the collection as you traverse it. But if you delete the Current member, where should Current point to? Can it point to the member of the collection immediately following the deleted member? Not really; Current and Next would then be referring to the same member. And if the iterator shifted the Next by one to avoid the clash, the same way it shifted Current by one, we might skip over the collection member that immediately follows the deleted member when the iterator's MoveNext method is called. As the .NET Framework documentation states:

The foreach statement is used to iterate through the collection to get the desired information, but should not be used to change the contents of the collection to avoid unpredictable side effects. [emphasis mine]

My colleague Kyle then came up with a terrific idea: just count backwards! Start at the last member and iterate back to the first; and if a member is deleted, the loop still operates correctly. So now our code looks like this:

for (int i = tbl.Rows.Count - 1; i >= 0; i--)

{

    // everything else is the same as before

}

You might not think the great programmers grow up in Appalachian hill country, but Kentucky Kyle has been full of pleasant surprises for us ever since we were astute enough to hire him. Or maybe they just have to deal with field sobriety tests a lot more in the Kentucky hills. Whatever the background, my hat is off to Kyle for his excellent idea.

Test-Driven Design: Make Sure You Fail!

Chris Falter — Sat, 20 Oct 2007 18:39:53 GMT

The idea behind test-driven design (TDD) is to incorporate testing into the process of constructing your system, rather than waiting for developers to check in their code and to build a system that someone else tests. TDD has some advantages worth considering:

Defects are identified sooner in the development process, which makes delivery of a reliable system cheaper and quicker.
Developers have more scope to improve the quality of code by refactoring, since they can run unit tests as they are making changes to verify whether the system still behaves as expected.
Unit tests serve as built-in documentation on how to call and make use of interfaces.
This built-in documentation is guaranteed not to go out of date. (You've never had the joy of working with out-of-date documentation, have you? You haven't lived until you've debugged some code whose documentation does not match. Or perhaps I should say, you haven't worked in software development unless you've debugged, etc.)
A team can run unit tests in the final step of the build process, in order to verify that the new build has no obvious defects.

The test-driven design process goes like this:

Get the requirement from the customer.
Design a test suite that will verify that the requirement is satisfied.
Run the test suite and make sure it fails.
Write code and run the test suite until it succeeds.

When the test suite succeeds and there are no obvious ways to simplify the code, the developer performs his customary victory dance and checks in the code.

I have incorporated TDD into the development process for some web services that have multiple customers. If we did not have a more or less complete suite of unit tests, any modification would be hard to manage. Any codepath that any customer relies on could have a regression when any code is changed, right? So in the absence of TDD, any modification would require that several testers (Pat, Tammy, and Charles at our office) spend a fair amount of their precious time running regression tests. Consequently, I have created suites of unit tests to verify that no regressions have occurred, and have even given them names ("virtual Pat," "virtual Tammy," and "virtual Charles") . Virtual Pat and her virtual colleagues are working hard so that the real Pat and her colleagues can head home at 5pm.

Recently I received a requirement to modify a service method so that it would return extra data. After I revised the unit tests, I almost skipped over step #3 (make sure the test fails). After all, I was in a hurry, and why bother? Aren't my coding skills good enough to write a simple test?

Evidently not.

I ran the test suite and it did not fail. I rubbed my eyes in disbelief and ran the suite again; of course, it succeeded again. A quick glance at the tests showed that the test suite contained the extra data expected from the method, but I had failed to write the assertions that would compare the expected data with the actual data returned from the method. So if the actual data returned from the method was not correct, the test (and the developer) would never know it. Doh! <Sound of hand smacking forehead />

So I added the assertions, ran the test suite (Hurrah! It failed!), wrote the new code, ran the test suite again, and it succeeded. I checked in my code, and it's working as expected.

The moral of this tale is simple: in test-driven design, you have to fail before you can succeed.