Mystery Constants: Maintainability

Working with legacy code is always one of my favorite things to do.  I believe it helps me write more maintainable code, and the little mysteries are always quite engaging.  The most recent example that I feel compelled to share is related to the setting of a database value based on the selection made in a radio button group.  In this particular instance, a set of custom localization routines help cloud the issue by abstracting the text from the code, but the central fault is more universal.  There was an undocumented naming convention that was initially followed within the database, but the constraints on columns were not always put in place to enforce the convention and the code itself was not designed to assist in any way.

On to specifics (altered to insure confidentiality).

• Initially, in the UI there are three radio buttons that correspond to an integer column in the database (color).  The value is set on a public property of an object that corresponds to the table (widgets) in the database.  There is a corresponding dimension table (widgetColorCode) in the database, but there is a missing foreign key constraint and the naming convention doesn’t make it easy to track down the dimension domain.
• Time passes.
• A new UI is built for a new company that only manufactures red Widgets.  The combo boxes are removed, and the value is set upon submission to the constant 1.
• A derivative of the new UI is commissioned that is for a company only supplying blue Widgets.   There is nothing in the code to help the programmer find what value this property should have.

So the code for the Widget class looks something like this:

 public class Widget
 {
 public int Color { get; set; }
 }

I am a firm believer in having enumerations corresponding to all dimensions in a project.  There is a performance hit for converting an enumeration to an integer, but it is far outweighed by the increased maintainability of the code.  By explicitly setting the values for the enumeration and adding an XML comment relating it to the dimension table, you can greatly increase the maintainability of the code. When starting from scratch on a project, I will typically have something along the lines of:

 ///
 /// corresponds to the Widget fact table
 ///
 public class Widget
 {
 public WidgetColor Color { get; set; }
 }

///
/// corresponds to the WidgetColorCode dimension table
///
public enum WidgetColor
{
Red = 1,
White = 2,
Blue = 3
}

But, that is a personal preference, and refactoring the entire code base at this point can’t be justified.  What can be done quickly to lessen the impact of this when further maintenance is required?  Visual Studio comes to the rescue!  By simply adding an XML comment to the property, we can define the dimension so that hovering over the property will display the dimension information (Please excuse the missing pointer in the image, trust me, I am hovering over the Color property.):

 ///
 /// corresponds to the Widget fact table
 ///
 public class Widget
 {
 ///
 /// corresponds to the WidgetColorCode dimension table
 /// 1: Red, 2: White, 3: Blue
 ///
 public int Color { get; set; }
 }