How to Write Code that Doesn't Suck...Part 2 - OOP and the Open/Closed Principal

Welcome to Part 2 of the ever growing, popular web series, How to Write Code that Doesn't Suck!  Today I want to go over the Open/Closed Principle of OOP.  By discussing this principle, we're also going to cover Liskov Substitution and Interface Segregation (the L and I of the SOLID principle). 

In simplest terms, the Open/Closed Principle means code is open for extending but closed for modification.  I know, it sounds techy, but all it means is once code is released to your client, it should have been written in a way we can extend the behavior without modifying the original source with a heavy hand.  Why wouldn't we just modify the original source to match our new requirements?  Because the original code has gone through the software lifecycle.  It probably had research, design and code reviews, unit testing, marketing, etc... associated with it.  By you changing that original source, anything touching it might need revisited, best case retested. So if we can write code properly, the idea is we can extend behavior without being invasive to the existing production code.

Well then, how do we do that?  You have a choice.  Either use abstract base classes or interfaces.  What's the difference?  You should choose an abstract base class when there is definite behavior the base class can provide subclasses.  If there is no consistent behavior, then use interfaces to create a code contract.  So how does this help us?  Let's peek at some example code. 

The easiest example I can think of is logging.  We have so many log destinations these days.  We can write to a physical file, a database table, table storage in Microsoft Azure, other cloud storage, the Windows desktop event viewer, etc...

Let's pretend we have an app in production that writes to a physical file that is circular.  Circular file means once the tail reaches a certain length of bytes in the file, the file wraps back around to the beginning.  It is beneficial for tracing, but for situations of auditing to maintain a large history of actions, it stinks.  Well one of our clients is mad because an employee changed a record they shouldn't have and nobody knows what the old value was because the log overwrote itself removing the audit entry showing the change.  They're screaming at the CEO this is unacceptable and we must address it in the next release or they're moving to a competing product.  They're demanding we create a database table to store auditing rather than the physical file.  How can we write code allowing us to make this change without modifying the code surrounding this logging?

To start, let's look at bad code.  More than likely, we've all experienced the following:

public class Widget
{
   private readonly FileLogger _log;
 
   public int Value {get; private set;}

   public Widget(int value)
   {
      _log = new FileLogger();
      Value = value;
   }
 
   public void ChangeTheWidgetValue(int newValue)
   {
      _log.WriteEntry(string.Format("Changing the Widget Value from {0} to {1}", Value, newValue));
      Value = newValue;
   }
}

This works.  It tracks the old and new values in the log.  It probably met the requirements established.  I can't argue that.  However, while functionally correct, there is a major problem with this code.  This issue is called coupling.  We have coupled our FileLogger class to our Widget class.  The Widget class could care less where the log is written, it's just telling the log to track the change.  To meet our client's demands, I now have to change the Widget class to not create me this logger but one that writes to the database.  What if I have 100 classes performing complex work and audit that work using the FileLogger?  I have to change those as well.  That's a minimum of 100 changes, and all should be retested.  This is a major headache.

But wait...What if this horrible code didn't exist.  What if we went back in time, thought things through and wrote decoupled code making the product codebase maintainable and extensible?  What would the Widget class look like then?

To start, we need an interface called ILogger.  I'm using an interface because there is nothing we can share between a database logger and a file logger through an abstract base class other than method names.
  
public interface ILogger
{
   void WriteEntry(string entry);
}

Now, we need our FileLogger class, which will implement the ILogger interface:

public class FileLogger : ILogger
{
   public void WriteEntry(string entry)
   {
      ...
   }
}

Now I can inject this logger dependency into the Widget class by making the Widget ask for an ILogger in its constructor:

public class Widget
{
   private readonly ILogger _log;
 
   public int Value {get; private set;}

   public Widget(ILogger log, int value)
   {
      _log = log;
      Value = value;
   }
 
   public void ChangeTheWidgetValue(int newValue)
   {
      _log.WriteEntry(string.Format("Changing the Widget Value from {0} to {1}", Value, newValue));
      Value = newValue;
   }
}

See what's happening here?  In the first example which is very badly designed code, we're coupling the Widget class with a FileLogger.  Now to change to the Database Logger, I have to break that coupling everywhere it exists.  With the second set of code, which is decoupled, I just have to do the following:

Create the DatabaseLogger and implement the ILogger interface:

public class DatabaseLogger : ILogger
{
   public void WriteEntry(string entry)
   {
      ...
   }
}

Next, wherever I'm creating the Widget, I just pass a DatabaseLogger object instead of a FileLogger.  Then I just rinse and repeat wherever we need to audit to the database.  The Widget class never has to change because it is not coupled to a specific class.  Rather, it is coupled to a code contract by use of an interface (Liskov Substitution).  As long as I pass something implementing the code contract through the ILogger interface, I only need to change where the Widget is instantiated.  This now allows your QA department to use the app as normal and just ensure audit entries are written to the database.  Even better is maybe there are clients that like the circular audit file because it saves storage space.  We can add a config option to use File or Database logging, and based-on that value, inject the appropriate logger (Interface Segregation).  If you follow these principles, you will surprise yourself with your own code, especially if you have to revisit it in the future.

In the next post, I'm going to cover Dependency Injection and the D in the SOLID principles, Dependency Inversion.  It may take a few days to write, both are large subjects to cover, but if you understand them, your code will make you happy!

Since I write this stuff on my own time, I usually blaze through it.  If you want more detail or if you find any technical errors, feel free to post a comment.  If you want to correct my grammar or point-out typos, go walk the plank, I'm a software engineer not a literary mastermind.  After years of programming, sometimes you lose grasp of writing with proper English.

How to Write Code that Doesn't Suck...Part 1 - OOP and Single Responsibility

I was enrolled in college for my BS in Computer Science from the mid-90s to 2003.  My father had health issues which led to money issues, so I was forced to put myself through college.  After 8 years of working weird jobs and finishing my degree with part-time and full-time schooling from Auburn University in Auburn, AL (WAR EAGLE!) and Wright State University in Dayton, OH, eventually I achieved my BS in Computer Science.

What does this have to do with Object Oriented Programming?  Nothing.  But, I did receive OOP instruction from two universities and I think both taught it strange.

I was taught an object is a thing.  I was taught inheritance is something like a Shape class, then if I want a circle, I should create a Circle subclass that inherits the qualities of the Shape base class.  While this provided a decent enough understanding of OOP, enough where I could pass tests and write coding projects, once I hit the real world, it wasn't enough.

Objects are more than things, 'thing' isn't granular enough.  Luckily for me, early in my career, I read about the SOLID principle (SOLID on Wikipedia) and I've been living by it ever since. 

What really caught my attention, is the idea objects should represent a single responsibility rather than being, simply put, a thing.  In OOP, an object does not have to be something tangible.  It doesn't have to be a shape, it could be a database reader.  It could create objects, it could be a jersey on a player in a video game, configuration manager, etc...Sure it's a thing, but if you focus on objects encapsulating responsibility rather than tangibility, I guarantee your code will be more clean.

As a novice software engineer, the hole I was always fell in was by thinking an object was tangible, I never encapsulated the inner responsibilities of the thing.  Let's take the player jersey in the video game as an example.  I would code a class called PlayerJersey.  PlayerJersey would have a string number property and a string last name property.  It would have a color property, is it mesh, does it have trim, etc...Before I knew it, I was managing all that data in one class because all those properties are on a PlayerJersey.  The product was an object that was not easily maintainable and it would hide behaviors and properties that I could have reused in other classes.

Now, let's think of the PlayerJersey as a responsibility and let's think of those properties as other responsibilities.  We should have a Name class, that contains the string name, but maybe it contains other info like the font and it manages all the properties of the Name.  We should have a Number class that is similar.  Maybe there's a JerseyFabric class managing the fabric responsibilities...so on and so forth.  If we encapsulate those inner behaviors into their own single responsibilities, the PlayerJersey class now becomes the manager of those objects.  All of the logic is now encapsulated into smaller classes and the PlayerJersey class becomes cleaner and more manageable.  The product is a number of re-usable classes managing a small subset of responsibility that when joined into another object creates another responsibility.  For example, if we have a Name class, we could reuse that on a stats screen, maybe a scoreboard style ticker in the game, etc...Also, we now know if there is a problem with how we handle names, then we can go to the Name class rather than updating the PlayerJersey class or any other classes which incorrectly encapsulated the Name responsibility.

I know this was a quick blog entry.  It's purpose is to wet your feet on how I think when I lead projects.  In Part 2 we're going to discuss the Open/Closed principle of SOLID and how not following it can make a good app go bad.


Since I write this stuff on my own time, I usually blaze through it.  If you want more detail or if you find any technical errors, feel free to post a comment.  If you want to correct my grammar or point-out typos, go walk the plank, I'm a software engineer not a literary mastermind.  After years of programming, sometimes you lose grasp of writing with proper English.

IDataErrorInfo Holds the Power of Grayskull

When I first started using XAML, one of the things I discovered for myself was the use of IDataErrorInfo.  IDataErrorInfo is an interface you can implement to allow XAML, through Bindings, validate the input in your UI fields.  Then, through Style Triggers watching the result of the validation, you can alter how your fields look to give the user a visual display that something is not correct.

I have written a quick example project you can download here:  blog.sln.  Please note, for this solution to work properly, you will need to download the latest version of MVVM Light Toolkit.  Also, I'm assuming you have minimum experience with MVVM and binding.  If not, I suggest you read this article.

To start using IDataErrorInfo, you will need what I like to refer to as a Presenter object.  For now, just consider a Presenter something similar to a ViewModel.  In a future blog post, I'll discuss why I choose Presenter over ViewModel.  Trust me, there are many benefits, especially if you use Resharper.

In the example you can download, I have created a MainWindowPresenter which extends/inherits ViewModelBase and implements the IDataErrorInfo object.  Since this is such a simple example, there is no need to break things down into more presenters.

When you implement IDataErrorInfo, there are two properties that need implemented:  Error and Item.  I rarely implement the Error property because it only returns a single error describing what is wrong with the entire object.  However, the Item property returns a string which indicates what failed with the validation of a property being bound to.  This means, that for each property that is available in my Presenter, when that property setter is called, this Item property is called.  So each time a property value changes, I have a hook to validate the value.  By using Item, I can generate a more granular error message as opposed to a single error message for the object.

The example you can download is a simple WPF application.  It has 2 fields and button.  The idea is to enter a Last Name and First Name and then if you click the button, it will display a message formatting the name Last Name first.  For this example, our business logic is Last Name is a required field but First Name is optional.  We should not allow a user to press the Show Name button unless they have at least entered Last Name.  We should also provide some visual cue that Last Name is required.  In this example, I have chosen to display a dark red border around the Last Name TextBox with a soft red background.

Here is my code for the Item property:

public string this[string columnName]

{

   get 

   {

      switch (columnName)

      {

         case "LastName":

            return string.IsNullOrWhiteSpace(LastName) ? 

                      "Please provide a Last Name" : 

                      null;

         default:

            return null;

      }

   }

}

The columnName parameter is the name of the public property you are binding to.  In this case, I am binding to the LastName public string property.  When LastName's setter is called, the code above is called to validate the value.  In this case, if LastName is null or whitespace, I return a string message explaining why the validation failed, else I return null.  By returning null from the Item property, you indicate validation is successful.  By returning a string, you are indicating validation failed.

The next step is on the XAML side in the Binding of the Last Name TextBox.  To enable validation you must set ValidatesOnDataErrors to True and NotifyOnValidationError to True.  Below is my XAML for the LastName TextBox:

<TextBox Style="{StaticResource ValidatingTextBox}" 
         Text="{Binding Path=LastName, 
                        Mode=TwoWay, 
                        UpdateSourceTrigger=PropertyChanged, 
                        ValidatesOnDataErrors=True, 
                        NotifyOnValidationError=True}" />

By setting UpdateSourceTrigger to PropertyChanged, I am telling my Binding to update the LastName property each time the Text value changes.  This ensures as soon as someone types into the LastName TextBox, we start validating.

The next items to discuss involve the styles associated with this Window.  I have a DefaultTextBoxStyle that sets the basics of the TextBox such as Height, Width, and alignments.  I then have a ValidatingTextBox style that investigates the Validation result of a TextBox and changes the color and tooltip if there is a Validation error.  Below are the styles:

<Style x:Key="DefaultTextBox" TargetType="TextBox">
   <Setter Property="HorizontalAlignment" Value="Left" />
   <Setter Property="VerticalAlignment" Value="Top" />
   <Setter Property="Margin" Value="5,0,0,0" />
   <Setter Property="Width" Value="150" />
   <Setter Property="Height" Value="25" />
</Style>
<Style x:Key="ValidatingTextBox" TargetType="TextBox" BasedOn="{StaticResource DefaultTextBox}">
   <Style.Triggers>
      <Trigger Property="Validation.HasError" Value="True">
         <Setter Property="ToolTip" 
                  Value="{Binding RelativeSource={x:Static RelativeSource.Self}, 
                  Path=(Validation.Errors)[0].ErrorContent}"/>
         <Setter Property="BorderBrush" Value="#D10000" />
         <Setter Property="BorderThickness" Value="1" />
         <Setter Property="Background" Value="#FFBACD" />
      </Trigger>
   </Style.Triggers>
</Style>

Looking at the ValidatingTextBox style, you can there is a Style trigger based on property Validation.HasError.  When Validation.HasError is true, I access the Validation.Errors collection and grab the ErrorContent of the first error in the collection.  This will display the string result from the Item property as the tooltip.  So by simply implementing IDataErrorInfo and returning a string if a binding value isn't valid, with this style, I can provide a tooltip message and a visual cue something is wrong.

The enabling/disabling of the button is handled by the MVVM Light ToolKit's RelayCommand object.  When creating a RelayCommand, you provide the executing method as the first parameter, and a validation as the second.  The validation method just needs to return true if it is possible to run the execution method.  I simply provide a method that returns true if LastName is not null or whitespace.

That's it!  Following this example, you should be able to show visual cues in your UI when required data is missing, in an improper format, outside an acceptable range, etc...

Stay tuned for the next blog.  I will explain the pattern we use at my current place of employment, named CCP (Controller, Context, Presenter).