Thinktecture has announced that their popular Web Service Contract First tool (WSCF) has been made available as an open source project hosted on CodePlex.

I love using WSCF to build web service proxy interfaces for traditional asmx web services.  It is a fantastic tool that greatly improves upon the traditional “Add a Web Reference” functionality in Visual Studio.  The one thing I was always frustrated about it was the (lack of) speed of its development, and the timeliness of keeping up with .NET releases.  Hopefully, the open source community will rise to the challenge and improve upon an already solid product.

Looks like a busy end of the month for me.  I am going to try to attend the following events in the next two weeks:

Atlanta Geek Dinner

Shawn Wildermuth is hosting another Geek Dinner on the north side of town, at Pappadeaux’s in Alpharetta on October 23rd.  I’ve missed the last few, so I’m really looking forward to getting back in the mix on these.  I love Pappadeaux’s, but hate the fact it’s in Alpha-tucky.  Oh well.

Pappadeaux Seafood Kitchen
10795 Davis Dr.
Alpharetta,GA 30004
770-992-5566

Agile Atlanta

The Agile Atlanta User Group is deviating from their usual scheduled meeting of every 2nd Tuesday of the month for a special event on Monday, October 27th.  Jeff Sutherland, the co-creator of Scrum and one of the authors of the Agile Manifesto is presenting at Turner’s Techwood Campus location.  The topic is titled, “Hyperproductive Distributed Scrum Teams”.  This is an amazing opportunity to hear one of the true leaders in the Agile community speak.  Turner has very tight security, so they are asking anybody who wishes to attend sign up beforehand.  You will need to sign up and present a photo ID for admittance into the building.

Techwood Campus at Turner
(1015 Assembly Room)
1050 Techwood Drive N.W.
Atlanta, GA 30318

Atlanta ALT.Net

The Atlanta ALT.Net group is holding another meetup on Wednesday, October 29th at Thinking Man Tavern in Decatur.  The topic of this meeting is Continuous Integration.  Josh Gough has done a great job organizing these meetings, and I look forward to another interesting and lively discussion.

Thinking Man Tavern
537 W Howard Ave
Decatur, GA 30030

During our daily standup the other day, one of the developers was complaining about the lack of commenting in a module that was written by a 3rd party consulting firm.  This got many frustrated nods from the other developers in the group, which in turn led to a discussion of comments overall in our code.  There seemed to be a general consensus among the group that the commenting in our code needed to be improved overall.

The reason I found it interesting (and by interesting I mean to me only) was the the timing of it all. 

I’ve been on a kick lately to read nothing but Agile books (instead of the usual books on specific languages or technologies).  The one currently occupying my bedside table is a book by Robert C. Martin (aka “Uncle Bob”) called Clean Code : An Handbook of Agile Software Craftsmanship. 

Literally only a day or two before this particular stand-up meeting, I had read the section on commenting in the book.  In fact, Uncle Bob’s views on the subject were so strong that he dedicated an entire chapter to it.  He argues that comments overall are a “necessary evil” and are only needed as a means “to compensate for our failure to express ourself in code.”  He hopes someday that languages evolve to DSLs that are self-documenting.

He reasons that comments are bad because Agile code changes over time.  Oftentimes, the comments don’t get maintained along with the code.  So the more code gets changed, the comments become further away from the current intent of that code.  In fact, he boldly states that comments lie (though not necessarily intentionally), and that inaccurate comments do more harm than no comments at all.  A bad comment is worse than no comment (maybe Uncle Bob was a lawyer in a former life?). 

Well, if that’s the case, why bother commenting at all?

He does give some examples of useful comments:

• Legal comments, such as copyright headers, author statements, or ownership rights
• Warning of consequences
• TODO comments, which can be caught in IDEs as warnings

On the other hand, he provides numerous examples of bad comments:

• Documenting a “hack”
• Comments that mirror the functionality and/or naming of the code piece it describes
• Poorly written comments, which can be harder to read than the code itself
• Journal comments that log each time the code is changed
• Noisy comments that provide no value (e.g. // ignore )
• Position markers (e.g. //////// Public Methods /////////////)
• Closing brace comments (e.g. // end while)
• Commented out refactored code (a personal pet peeve of mine)

I don’t know if I agree with the extremist approach of removing all comments from my code.  But I do agree that comments are often abused as a replacement for good code.  The rule of thumb I came away from the book is: if you feel the need to document a complex chunk of code with a comment, that is a sure-fire sign of a code smell.  Step back and look at the code from an maintenance perspective.  Is this code likely to change?  What are the odds the comments will change with it?  Is the comment articulating my intent well?  Have I named my variables/methods/classes intuitively?  Most importantly - can I refactor the code into a standalone method that can be named expressively?

Comments can be useful, but many times end up being the poor man’s excuse for lazy coding.  Don’t be that guy (or gal).  Strive to make your code readable without having to resort to comments.

I heard on the latest Windows Weekly podcast that Microsoft has posted a new update to their Live application suite.

The Windows Live Wave 3 release includes updates to two applications I use frequently - Live Writer (which I’m using to write this blog post!) and Live Messenger.  The changes aren’t overwhelming, but do add some polish to the UI and give it a little more of an “Aero” type feel. 

I've come across all kinds of architectures in my time.  Some have been good, some bad (yet somehow the bad vastly outnumber the good).  Even on some of the good architectures I've seen, a common problem I've found is the abuse of object inheritance. 

It's tempting to create an inheritance hierarchy to quickly get all the functionality provided by a common base class.  Through one little symbol or keyword, you can easily extend your object to get all the functionality provided by some other class.  However, be aware this kind of modeling comes with a price, and many times it's a price more steep than you should be willing to pay. 

Which is why a lot of people much smarter than me - Josh Bloch, Venkat Subramaniam, Andy Hunt, Dave Thomas, Robert "Uncle Bob" Martin, and Steve McConnell - have all argued that using composition instead of inheritance creates a much more Agile object model.  There are many reasons why Agile developers feel this way.

Conceptually

"Is-a" vs. "Has-a"

In inheritance modeling, class inheritance should only be used to represent true "subtype" relationships.  Every subclass should be a subtype of the class it is extending.  Object B should only extend Object A if a logical "is-a" relationship exists.  In other words, you need to ask yourself, "Is every B really an A?"  If you cannot truthfully answer yes to this question, there is no reason for B to extend A other than simple convenience.  And convenience is not a good reason for creating an inheritance hierarchy. 

Steve McConnell explains further in his seminal book Code Complete,

"If the derived class isn't going to adhere completely to the same interface contract defined by the base class, inheritance is not the right implementation technique."

Rather, you are better served modeling a "has-a" relationship between the two classes, where A is a private instance in the implementation details of B.  B may depend on the services provided by A, but is not a logical subtype of it.  By "wrapping" the reference to A, you will have a more conceptually accurate and flexible implementation.

It's all about the context!

A consumer of an object should be able to intuitively decipher its purpose from its public API.  When you force an inheritance hierarchy of two objects that don't have an "is-a" relationship, you have created an subclass object that contains methods, properties, fields, etc. from two different contexts.  By combining these contexts, you have created a confusing API that causes the consumer of it to have to actively track down the meaning behind methods exposed from the two contexts.

For example, suppose I have an Account object that extends TransactionCoordinator.  The two objects have two different contexts, and the design of their individual APIs most likely reflect that fact.  As a consumer of the Account object, when I see methods such as Start(), Commit(), Rollback() that have been inherited from the base class representing a different context, I am confused.  Intuitively, an Account is not a TransactionCoordinator, and I would have to know that inheritance relationship even exists to understand why I am seeing these methods.  Normally, I wouldn't expect to see them there.  What do these methods mean?  What do they do?  If I'm lucky, I can look at the API documentation (if it exists) on the Account object and it will detail each method and its functionality and implications when called from the subclass.  More likely, I will have to open the Account object up, see that it extends the TransactionCoordinator, and go there to research what each method actually does.  And only then can I have the ability to decide if that behavior is something I want to invoke on my subclass.

Here’s the lesson - don't make consumers of your API work any harder than they have to.

Liskov's Substitution Principle

Barbara Liskov wrote one of most ground-breaking papers on object-oriented programming in 1998.  In this paper, Liskov proposed that you shouldn't inherit from a base class unless the derived class truly "is-a" more specific version of the base class.  In what became known as the "Liskov Substitution Principle", Liskov argued that any derived class must be able to be completely substituted for its base class interface without any knowledge of the calling class.  In other words, subclasses must only change the implementation and not the meaning or intent of the base class interface. 

Say you have an abstract base Account object.  Callers that reference the base class API should not have to know or care which whether a CheckingAccount or SavingsAccount derived class actually provides the implementation.  To take the example further, suppose there is a CalculateInterest() method declared on the Account object.  In normal implementations it calculates the interest due to the consumer.  Suppose you introduce a BankLoanAccount which changes the implementation to calculate the interest for the bank.  This class violates the LSP since it changes the meaning of the implementation of the CalculateInterest() method, so now the caller cannot freely call the method on the base class reference.

Single Responsibility Principle

I'm a firm believer in the Single Responsibility Principle.  Classes should have one responsibility, and one responsibility only.  Think of it as the old Henry Ford assembly line - classes should do their one thing and do it well.  There is no reason for them to know the inner details or the workings in the classes in which it interacts.  This leads to smaller, more focused classes.  And small, purposeful classes are A GOOD THING. 

Single responsibility creates classes that are highly cohesive, while limiting coupling to external dependencies.  High cohesion and low coupling is an admirable goal in any software architecture.

Planning for change

By limiting classes to one responsibility, you are also creating a class that has only one reason to change.  As a developer who believes in Agile methodologies, I know change is going to come.  Limiting the reasons for classes to change, as well as the surface area in which that change will be felt, will go a long way towards making those changes easier to implement.

Technical

Introduces Dependencies

Anytime you inherit from a class, you are explicitly creating a dependency on that super class.  The code to the super class may change over time.  Each time it does change, it can potentially directly or indirectly break some or all of its subclasses, even though the code in subclasses may not have changed at all.  Most likely, the subclasses had no idea the change even occurred at all.  And unless you have planned for this contingency in your unit test (you are writing unit tests, right???), you may not even find this breaking change until after the code is deployed.  And if you are writing unit tests, that's just more (seemingly avoidable) unit tests you need to write to handle these cases.

This creates a lot more work for the API producer.  All subclasses now will have to be designed (and tested) to evolve in conjunction with their super classes.  That's more code and more unit tests you now have to write and maintain.

Fragile classes

Due to rules we must live with when choosing a static, compiled language, we limit ourselves in the structuring of our API.  Anytime we define a method signature in any class, this signature causes a ripple effect up and down the inheritance hierarchy.  That's both good and bad.  Each base class automatically inherits the new functionality, but guess what - it may not want to do so.  Or worse yet, it can break existing functionality in the subclass.

For example, introducing or changing a method signature in the base class will flow down to every class that derives from it.  What if that subclass already has a method defined in that class with the same name?  This will cause either: a compilation error if the method cannot be overridden; or worse yet unexpected behavior at runtime if the method can be overridden as the subclass implementation is now unknowingly invoked.  Or, what about if the subclass has the same method name but a different signature?  You will be forced to change your API in one of the classes just to get them to compile.  The same problems manifest itself as methods are introduced in base classes, but at least you are a probably little more aware of the potentially breaking changes.

Think this is a far-fetched example?  I don't.  Imagine common method names like Execute(), Activate(), Register(), or IsAvailable(), Open(), Load(), or Save().  All of these are all methods names that are prolific in our object models, and could easily have much different signatures as well as potentially meaning very different things in different contexts.

What if the behavior introduced in a base class implementation is not desired in the subclass?  Sorry, your S.O.L.  Good and bad, you get everything that comes down from the base.

Refactoring

Due to all the problems with carrying "API baggage", classes with deep hierarchies are much harder to refactor.  Are you completely comfortable with the API provided by your super class?  Because anytime you extend it, any flaws/issues/concerns you have with it are propagated down to the subclasses.  Not only that, the flaws now become further spread across your object model through the expanded surface area of all of its own and now its subclasses consumers.  Composition is much more flexible.  It has the advantage of masking, improving, or changing the API to encapsulate the existing concerns.

Not only that, but now you have tied yourself to this mis-matched inheritance hierarchy, and it will be much harder to introduce a new base class if a new valid one ever presents itself.

Summary

Inheritances is one of the most powerful and most abused concepts in object-oriented programming languages today.  True, inheritance is an easy and useful way to provide quick code reusability across your object model.  But the drawbacks of doing so far outweigh the short-term gains achieved.  Oftentimes the reusability gained comes as the expense of code extensibility, maintainability, and testability.  In the long run, ironically both producers and consumers of the API will have to do more work to maintain the fragile inheritance hierarchy.  Favor composition over inheritance to limit fragile inheritance hierarchies and create a much more flexible and powerful API.

The Atlanta ALT.Net user group is meeting again this Wednesday, September 24 at the Thinking Man Tavern in Decatur.  If you plan on attending, the organizers are asking people to RSVP in order to get an accurate head count. 

We are going to spend some time talking about ASP.Net MVC, but I imagine it will be open to discussion on all topics.  Hope to see you there!

View Larger Map

My friend Brad Anderson is putting together a meetup for the Metro Atlanta Erlang Users Group.  They are planning their initial meeting to be at The Brick Store Pub in downtown Decatur this Saturday (September 20th) at 7pm. 

Unfortunately, I am probably not going to be able to make it since it's my anniversary weekend, but if you are at all interested in Erlang (or functional languages of any sort), it should be a good time.  He told me people are coming from as far away as Raleigh just for this meetup.  And if you enjoy good beer (who doesn't???), it doesn't get much better than the Brick Store.

In my last post, I showed how to write stuff out to a temporary directory.  After I wrote the post, I started thinking about how people could misconstrue the meaning of it.  The post was intended to show how to dump stuff easily to a random directory on the file system.  The code that drove me to write that particular example came from a unit test that was using the temporary directory as a repository for the output of the XmlSerializer.  In other words, I really was not doing anything meaningful with the data.

To clear things up, I thought I would write a post that showed how use a unknown storage directory as a meaningful repository for application data.  What constitutes meaningful data?  I don't know, it's your app!!!  But common possibilities include application settings, user-specific data, etc...  I'm thinking of things that might be otherwise be stored in the registry.  Yeah, don't do that anymore.  I don't know about you, but the just the word "registry" causes me to shudder.

.Net has introduced a new concept called "Isolated Storage" to hold this type of information.  Isolated storage is an unspecified location on the file system that is hidden away from the application.  Even though the location is unknown, the application is guaranteed to have full permissions to it, even if it is running in a restricted security mode.  As it name implies, the location is "isolated" so that any data written to it does not affect other applications or anything else on the file system.  So as far as security goes, you're limited to only hurting yourself by maliciously or ignorantly (mis)using this repository.

Here's a code sample of how you would use it to store data:

// get the location specific to this user/assembly
IsolatedStorageFile isf = IsolatedStorageFile.GetUserStoreForAssembly();
// create a file to write the data to 
using ( var outStream = new IsolatedStorageFileStream("foo.txt", FileMode.Create, isf) ) 
{
    using ( var sw = new StreamWriter(outStream) ) 
    {
    	// write out the text
        sw.Write("Random text");
        sw.Close();
    }
}

And here is how you can retrieve it:

IsolatedStorageFile isf = IsolatedStorageFile.GetUserStoreForAssembly();
// open the file
using ( var inStream = new IsolatedStorageFileStream("foo.txt", FileMode.Open, isf) ) 
{
    string[] files = isf.GetFileNames("foo.txt");
    if ( files.length > 0 )
    {
        StringBuilder sb = new StringBuilder();
        foreach ( var file in files )
        {
            using ( var sr = new StreamReader(inStream) )
            {
                sb.AppendLine(sr.ReadLine());
            }
        }
    }
}

This method is a much more "enterprise-y" way to access data in your applications.

Have you ever found the need to use a temporary directory on the file system in your code?  This issue came up with me recently (and bit me in the ass), so I thought I would share some experiences on how I overcame the problem. 

At the root of the problem is that you need some sort of permanent storage, but nothing that is stringent enough to require it reside in some "known" directory where it can be accessed at a later time.  You don't really care where you store a file, but you need to store it somewhere. 

I recently came across a piece of code in a unit test that serialized a class using the XmlSerializer.  The person who wrote the test must have wanted to see what the class looked like in serialized form.  The code was written so that the xml version of the class was dumped to the file system.  However, when the test was written, the file was hard-coded to the C:\Temp directory. 

As part of my task, I was incorporating the unit tests on this component into the continuous build.  Guess what happened when the test was moved the build server?  FAIL!!!  No C:\Temp directory on that machine means lots of red on the build server and the IT director screaming WTF?!?!?

The lesson is, never make assumptions when accessing the file system.  In this case, the test was counting on the directory both existing and the user having permissions to it.  Obviously, that's not a good idea.

There are other ways to get to a valid "temporary" directory in .Net.  The following code sample shows how you can try a few known places in .Net that should work as "temporary" directories.

/// <summary>
/// Get a valid "temporary" directory on the machine that is running this code 
/// </summary>
/// <returns>a temporary directory</returns>
private string GetTemporaryDirectory() 
{ 
    // try this first 
    string dir = Path.GetTempPath(); 
    if ( String.IsNullOrEmpty(dir) || !Directory.Exists(dir) ) 
    { 
        // see if the "TEMP" environment variable is set 
        dir = Environment.GetEnvironmentVariable("TEMP"); 
        if ( String.IsNullOrEmpty(dir) || !Directory.Exists(dir) ) 
        { 
            // hmmm ... let's create one in "My Documents" 
            string myDocsDir = Environment.GetFolderPath(Environment.SpecialFolder.MyDocuments); 
            if ( String.IsNullOrEmpty(myDocsDir) || !Directory.Exists(myDocsDir) ) 
            { 
                // no "My Documents" directory??? 
                throw new Exception( 
                    "Cannot determine a valid temporary directory on this system. " + 
                    "Please set a valid directory for the \"TEMP\" environment variable."); 
            } 
            dir = String.Format("{0}\\Temp", myDocsDir); 
            if ( !Directory.Exists(dir) ) 
            { 
                Log.Info("Creating new Temp directory in {0}", myDocsDir); 
                Directory.CreateDirectory(dir); 
            }  
        } 
    } 
    if ( dir.EndsWith("\\") ) 
    { 
        // cut the last char off 
        dir = dir.Substring(0, dir.Length - 1); 
    } 
    return dir; 
}

The code example above tries to use the .Net libraries to query the file system for some well-known directories that can be used for temporary files.  If a valid one is not found, it will try to create a "Temp" directory in the current user's "My Documents" directory.  At worst, the user should have access to this directory, and the build should not break based on a hard-coded assumption.

Take a look at this little announcement that came out of OSCON last week...

http://port25.technet.com/archive/2008/07/25/oscon2008.aspx

Amazingly, Microsoft has agreed to join the Apache Software Foundation as a platinum sponsor.  Oh, in case you weren't aware, Microsoft has this little product called "IIS" that kind of directly competes against the open-source Apache web server.

Paradoxically, IIS would die to get the market share enjoyed by Apache, yet is neither free as in beer nor as in speech.  A fact that I imagine probably makes for a tough sell for the Microsoft marketing department.

The cynics are saying this is a bold move by Microsoft to help ease the sting caused by the PR fiasco known as "Windows Vista."

"Hey, look at us, you might think we suck and are inherently evil, but suddenly we love open source (well, not anything that is GPL'ed - but I guess that's just common sense)." 

I honestly don't know what to make of it.  I guess in the grand scheme of things, the $100,000 ponied up to join Apache can't even be considered a drop in the bucket for Microsoft.  As they said on TWiT this last weekend, "That just gets them on the mailing list."

Maybe it's like Sun-Tzu said (and later echoed by Michael Coreleone in Godfather II), "Keep your friends close, but your enemies even closer."

The first(?) meeting of the Atlanta alt.net user group is going to take place this Wednesday at the Thinking Man's Tavern in Decatur (which is conveniently located fairly close to my house).  I have already RSVP''d.  If you want to come, sign up soon.  The web signup page says there are only 2 spots left.  Hope to see you there!

I ran into a piece of code today similar to this:

public class Base
{
    public Base()
    {
        this.Initialize();
    }

    protected virtual void Initialize()
    {
        Debug.WriteLine("Base.Initialize()");
    }
}

public class Derived : Base
{
    public Derived() : base() {}

    protected override void Initialize()
    {
        base.Initialize();
    }
}

public class FurtherDerived : Derived
{
    public FurtherDerived() : base() {}

    protected override void Initialize()
    {
        Debug.WriteLine("FurtherDerived.Initialize()");
    }
}

public class Tester
{
    public static void Main(string[] args)
    {
        Base myBase = new Base();

        Derived myDerived = new Derived();

        FurtherDerived myFurtherDerived = new FurtherDerived();

        Console.ReadLine();
    }
}

See any problems here?  Even though the compiler lets you call virtual methods from a base constructor, it's generally a "bad idea".  That's because the constructor in the derived classes defers its construction up to its base classes before it executes its own constructor (even if we don't explicitly call the base constructor like in the example).  Yet the call to a virtual function in the base class constructor is executed in the derived class implementation.  This can cause subtle, unexpected problems.

In the example above, things "happen" to go well.  It actually runs just fine.  It outputs the following as you'd probably expect:

Base.Initialize()
Base.Initialize()
FurtherDerived.Initialize()

But that's only because we didn't do anything significant in the derived constructors.  What happens if we change the FurtherDerived class:

public class FurtherDerived : Derived
{
    StringBuilder _sb;

    public FurtherDerived() : base()
    {
        _sb = new StringBuilder();
    }

    protected override void Initialize()
    {
       _sb.Append("FurtherDerived.Initialize()");
       Debug.WriteLine(_sb.ToString());
    }
}

Guess what happens when we run this code? FAIL!!! The dreaded, "Object reference not set to a reference of an object". Since the Initialize() method in the FurtherDerived class is called from the Base constructor, we are trying to access the _sb class level parameter before it's ever initialized.  We are calling a method on an class we know has not been fully constructed.  That ain't good.

The lesson is - never call a virtual method from a constructor.  At best, you are introducing a bug waiting to happen.  At worst, you've already done so.