Amazon.com Widgets Nick Hodges | A man's got to know his limitations

Using FreeAndNil

By Nick at December 13, 2011 16:39
Filed Under: Delphi, Software Development

There has been a large and ongoing thread in the Delphi Non-Technical newsgroup about the proper use of FreeAndNil.  It’s been contentious and a tad touchy, too -- just as I like it.  Winking smile  The discussion falls out into two schools of thought:  Those that use FreeAndNil liberally and almost everywhere, and those that use it not at all or only in very rare, specific cases.  The former argues it is “defensive coding”, while the latter argues that it is the coding equivalent of spraying perfume on a skunk. 

I am in the latter camp.  I am in the the latter camp for a very good reason:  because the latter camp is right.  Winking smile There’s almost never a reason to use FreeAndNil in the new code that you write. 

And I want to be clear about that – I’m talking specifically about new code.   If you have old code that was designed in such a way that the scope of your pointers wasn’t tightly contained, than yes, you’ll probably have to use FreeAndNil to make that code work right.  But if you are doing that, I hope that you recognize that it is a problem and plan to refactor the code to contain the scope of your pointers.   I’m totally aware that legacy code may very well require that you nil pointers because the scope of those pointers is not well managed.  I know this because our system has such code, and thus contains calls to FreeAndNil

So, anyway, here’s an explanation why I think that FreeAndNil should only be used very, very sparingly. 

Before I start, I want to add that this blog post is heavily influenced by the eloquent wisdom and excellent explanations of a number of people who participated in the thread, including Bob Dawson, Wayne Niddery, Rudy Velthuis, Joanna Carter, Mark Edington, and Pieter Zijlstra.  Any profundity, excellent examples, pithy similes, or clear descriptions of things are very likely a result of me reading their posts in the thread.

Introduction

FreeAndNil is a function declared in the SysUtils unit and was introduced in Delphi 4, if I recall correctly.  I myself suspect that it was added more because of customer demand than because the R&D Team felt some need for it, and I’m reasonably sure that if they had it to do over again, they would not have added it at all.  But there it is.

The code for FreeAndNil is as follows:

procedure FreeAndNil(var Obj);
var
  Temp: TObject;
begin
  Temp := TObject(Obj);
  Pointer(Obj) := nil;
  Temp.Free;
end;

That does seem a bit weird looking – you might expect it to look like this:

procedure FreeAndNil(var Obj: TObject);
begin
  Obj.Free;
  Obj := nil;
end;

But it doesn’t.  It looks the way it does for a couple of reasons.  First, the parameter passed needs to be a var parameter because two things need to happen.  The object referenced needs to be freed, and the reference itself needs to be altered  -- that is, set to nil.  Thus, you need the freedom to change both the reference and the thing being referenced that the var parameter gives.  Second, the parameter is untyped because when you pass a var parameter, “Types of actual and formal var parameters must be identical.” Given that, if you declared the parameter as a TObject, then you could pass only a TObject to the method and not any of its descendants.

For instance, the following code will not compile:

program WontWork;

{$APPTYPE CONSOLE}

uses
  SysUtils;

type

  TMyClass = class(TObject);

procedure Foo(var Obj: TObject);
begin
  WriteLn(Obj.ClassName);
end;

var
 MyClass : TMyClass;

begin
  MyClass := TMyClass.Create;
  try
    Foo(MyClass);
  finally
    MyClass.Free;
  end;
end.

I should point out that the use (or non-use) of FreeAndNil is not an insignificant and uncontroversial issue.  The thread that spawned this is typically long.  Allen Bauer, the Chief Scientist at Embarcadero, blogged about it, and quite a discussion ensued in the comments – so much so that he felt the need to blog about it again.  StackOverflow has a whole bunch of questions on the subject.  The VCL uses FreeAndNil in places that I wouldn’t necessarily approve of.   I think that in most places its use indicates, uhm, an “older” design choice that probably wouldn’t be made today, given newer language features.  In any event, clearly folks have strong views on this and that the use (or note) of FreeAndNil is not “settled science” (though I believe it should be…). 

Okay, So When Should You Use FreeAndNil?

In my mind, the answer to the question “When should I use FreeAndNil?” is “never”, or at least “Almost never, and if you must use it, make sure that there is a really, really good reason to do so and that you clearly document that reason”.  I myself have never (to my best recollection – I fully expect someone to find some obscure reference to code I wrote years ago that uses it….) used the procedure and see no possible scenario where I would want or need to in the code I write.  My recommendation is that you never use it either, because I don’t believe that you are writing code that needs it either (unless you are on the Delphi R&D team working in the bowels of the RTL, I suppose). 

Why I Don’t Use FreeAndNil and Why You Shouldn’t Either

There are a number of reasons why I don’t use FreeAndNil

First, a call to Free is sufficient. It gets the job done.  Free will, well, free the memory associated with your reference.  It does the job completely and totally.  Can’t do any more.  Setting a pointer to nil doesn’t get you anything.  The memory isn’t going to be more free or freed faster as a result of calling FreeAndNil.  Since it’s always a good practice to use exactly the right tool and nothing more, there’s no need to make the extra call.  Consider this – there’s no SetToZero call for integers, and if there were, why would you use it?  All code should be written with “considered intent,” and the indiscriminate use of FreeAndNil shows a lack of consideration and intent.

Second, using FreeAndNil where Free alone will do just fine obfuscates your code.  Using a call that executes unneeded instructions sends a message to future readers of the code that shouldn’t be sent.  A subsequent developer maintaining your code might look at the call and say “What the heck?  Why is FreeAndNil being used here and not just Free?  Is something going on here that I don’t know about?”  Time might then be wasted investigating, and a satisfactory answer may never be found.   Code that uses Free and FreeAndNil as exactly the same thing has reduced the amount of information that your code can convey.  And when you are dealing with something as important as memory management, you certainly don’t want to reduce the amount of information your code can convey.

FreeAndNil has a clear meaning – it is a very clear indicator that the pointer being freed has meaning outside of the scope where it is used.  If it doesn’t say that, then you shouldn’t use it.  If you use FreeAndNil when that is not the case, then you’ve sent a bad message to future maintainers.  Clarity in code is paramount – nothing should be done to decrease that clarity.  Code should be intentional and there for a reason.  Code that is there that doesn’t need to be can be misleading and distracting.  Misleading and distracting are not two thoughts that developers want crossing their minds while maintaining code. 

Free has meaning as well – it clearly states that the use of that pointer reference is now done and over with.  As noted above, there’s no need to call anything else.  The indiscriminate use of FreeAndNil fails to draw the clear distinction between Free and FreeAndNil.  Losing clarity in your code is bad, right?

Third, one of the justifications for using FreeAndNil is that it is defensive and that it protects against using a pointer at the wrong time.  The claim is that if a pointer is nil, and you then use that pointer, then you’ll know right away, and the bug would be easy to find. Thus, if you feel the need to use FreeAndNil to ensure that you don’t misuse a pointer somewhere, then it is very likely you have a design problem:  the scope of the pointer in question is larger than the use of that pointer in your code.  Or, in other words, the scope of a pointer and the scope of the use of that pointer aren’t the same and they should be.  If they aren’t , you are simply begging for trouble. 

If you want to really be persnickety, a variable that is broader in scope than it’s use is a form of a global variable.  And I would hope that we agree that global variables are bad.  If we can’t agree on that, well, then we can’t agree on anything.  Winking smile

Maintaining proper scope is critical to good, clean code.  I’ve discussed this before, and so I won’t go on about it here.  The germane point here is that if the scope of a pointer is of the “laying around waiting to be used”, then there is no limit to the mischief that this wayward pointer can cause.  So, if you don’t “leave a pointer lying around”, you can’t misuse it.  So, well, don’t leave a pointer lying around.   If you don’t leave roller skates at the bottom of the stairs, you can’t go careening down the hallway.   Keep your pointers and the use of those pointers in the same scope and you can’t misuse a pointer.  And you won’t feel the need to use FreeAndNil

And if you do use it for defensive reasons, you have to use it everywhere.  You have to use it in ever single place it is needed and you can’t miss a single place.  And, every single maintainer of the code after you has to as well.  One instance of not using it basically removes all the reasons for using it.  It’s a much better plan to simply control your scope and never feel the need for it. 

So, in the end…

In the end, I guess the argument for using FreeAndNil seems to boil down to:

“Of course I use FreeAndNil – it protects against bugs and makes other bugs easy to find, and besides, what’s the harm?”

Well, it would seem that none of those reasons is really true.  The real argument is:

“If your code requires you to use FreeAndNil to reveal and easily find bugs, then your design is wrong.  Good, clean code never feels the need to worry about errant pointers.”

Hey, look: design your code however you like. However, if you were to ask me, I’d say to design your code in such a way that FreeAndNil sends no signal, doesn’t find any bugs any sooner, doesn’t protect against anything, and thus becomes utterly superfluous.

Flotsam and Jetsam #51

By Nick at December 12, 2011 00:51
Filed Under: Delphi, Flotsam and Jetsam, Software Development, Three Sentence Movie Review
  • If you missed CodeRage 6, or you didn’t get to every session that you wanted to see (hear?), it is now all online.  That link also points to the latest offers and ways to find out more about XE2.  I love XE2, and think it’s the best Delphi ever.  And I say that not even using the FireMonkey/cross-platform stuff – so it’s even better than I think.  Winking smile
  • I was digging around in my boxes in the basement – we’ve moved a ton, and so I’ve got stuff scattered all over – and came across a CD labeled “Website”.  I opened it up, and lo and behold, there was a copy of one of my very first web sites, built with NetObjects Fusion.  It was fun to poke around and see some of my really old content.  (As a point of reference, the homepage has “This site was last updated on  Tuesday, December 18, 2001” at the bottom.  Remember when we used to do that?) Actually, I think some of the stuff will end up on my current site.  Winking smile  Not all the links work, but if you’ve been around a while, you might remember some of it.  Most of it was hand-maintained, but you can see where I tried to integrate in some early Delphi-based CGI stuff.   I actually still like the colors and the template.  Winking smile
  • The Generics.Default.pas unit is an interesting one – you may never have cause to use it directly, but it contains a lot of interesting stuff in support of the classes in Generics.Collections.pas.   It’s worth poking around in.  I was doing just that, and came across some interesting code – a function called (and I quote) BobJenkinsHash.  It is used rather extensively throughout the unit, and appears to be a general purpose hashing code.  Who is Bob Jenkins, you may ask?  Well, apparently he’s a guy that wrote a very powerful and useful hash function, and Embarcadero has utilized it as part of their generics library.  And here’s the interesting part – they created it using a set of GOTO(!!) statements whose use , well  -- I seriously can’t believe I’m actually saying this – actually kind of make sense.  The C code depends on the “fall through” nature of C’s switch statement, and the GOTO calls actually mimic that rather nicely.  I’m open to suggestions on how it might have been written better.  Winking smile (Again – I can’t believe I just said that, but there it is.)  And to redeem myself, I’ll chastise the author for not defining his interfaces in their own unit.  (Sorry, Barry – I had to do something to restore my street cred for actually liking the way the GOTO’s worked…..) Anyway, interesting little find in the bowels of the Delphi RTL.
  • I’ve added a new category, Three Sentence Movie Reviews.   I watch a lot of movies, and have all these aspirations of writing up movie reviews when I watch, but I never do because it takes too long.  So I thought I’d simply limit myself to three sentences in reviewing the film, and that way I might actually get the review done.  I might have to get a bit creative – sort of like keeping tweets to under 140 characters.  Should be fun.  If you read this blog via DelphiFeeds, you won’t see it as I’ll not be putting the Delphi category tag on them. Just another reason to subscribe to my real feedWinking smile

Three Sentence Movie Review: Soul Surfer

By Nick at December 10, 2011 14:21
Filed Under: Three Sentence Movie Review

Soul Surfer:  This is a beautiful and touching film about a very courageous young woman, Bethany Hamilton.  You are probably familiar with Bethany, who lost her arm in a shark attack, recovered, and went on to become a professional surfer.  I strongly recommend this film about faith, courage, and determination.

One Right Thing at a Time

By Nick at November 24, 2011 13:44
Filed Under: Delphi, General, Software Development, TechBiz

Wherein I discuss how to do things that you should be doing and how not to do things that you shouldn’t be doing….

Sometimes you tweet something and it makes sense to you, but then you realize that it also kind of begs for more discussion. 

For instance: “Things move so quickly that doing the *one* most important thing means it's less likely that you'll do the wrong things in the long run.” 

I thought that a little more explanation would be in order.  Let’s say you have ten cool features on your “Things Customers are Screaming For” list.  There are two basic approaches you can take to getting them done: You can do them in series or in parallel.  If you do them in parallel, you’ll get them all done sooner, but you may not get them done as thoroughly.  If you do them in series, it will take you longer to do them all, but you’ll likely get each one done more thoroughly.

However, doing them in series – that is, sequentially doing only the most important remaining item – has an added benefit:  It can help you not do things that you shouldn’t do.  You may have ten things on your “We need to get these done right away”, but as time passes, some of those things may prove to be not needed, overtaken by events, or just plain dumb ideas.  Doing things in parallel may mean that you get everything done sooner, but it also means that you might do something that proves to be a waste of time later on.

For example, if you have a team of five folks, and you have five ideas that take six man months each, you might give each person one idea to work on, and then six months later, you have all five ideas done. Great!  But uh oh! -- as it turns out, over the course of those six months, things changed and events transpired in such a way that two of the ideas weren’t really good ideas after all, and at the end of the six months you regret ever starting on them.  So in the end, you have three things done that needed doing, but have wasted your time on two ideas that you should have left undone.  Furthermore, since you only had one person working on each idea, you may not get a fully fleshed out solution, but instead, one that may have missing features or is not complete in some way.

But consider what happens if you work on them in series: say that instead of starting in all at once on the entire list,  you pick the single most important of the ideas on the list.  You focus your whole team on doing that one idea.  You will likely be able to get it done somewhat sooner, say in one or two months instead of the six months in our example. (Five team members working on a six man-month project will likely take a bit longer because of transaction costs.)  In addition, you will get a “five-headed” solution instead of a “one-headed” one, and thus the solution would likely be more complete, fleshed out, and feature rich.  In other words, you might very well end up doing one thing properly and thoroughly instead of doing five things not so completely. 

The added benefit comes when, after doing the most important project, you realize that one of the ideas you had originally thought was awesome isn’t really that awesome, and that you can take it off the list and not waste time on it. You might add another item to the list, or another item that was on the list suddenly becomes vastly more important than it was at the start of the first project.  Instead, you can repeat the process and start working on the next most important thing.  You end up with a very nice implementation of each project you do undertake, and you don’t do the projects that shouldn’t be done.

In a rapidly changing technical environment, that which looks like a no brainer in January might be old news by July.  Obviously you want to avoid working on that project.  A practical example might be that you are a software tools vendor, and people are pressing you to do, say, a development tool for Windows Mobile 6.  You could choose to add staff and get that request done sooner, or you could stay the course and do more important things, only to discover with massive relief that you didn’t do Windows Mobile 6 at all when Windows Mobile 6 becomes a legacy technology.  (Sound familiar? Smile

Now, I’ll grant that if you follow this plan, you’ll end up with fewer features in the long run.   But you’ll also end up with more complete features with less wasted effort.  You won’t have spent time on things you ultimately should not have.  It might take a little longer to get any particular feature to market, but in the above example, you’ll end up with three really solid features and no time spent working on things that you should not have worked on at all instead of five half-baked features, two of which were a waste of time.

Repeat this process enough, and it becomes much more likely that you will end up with a product that has the right – and fully rendered -- feature set.  In many ways, inefficiencies are the result of choosing to do the wrong thing.  If you keep your choices finely grained – that is, always put your efforts only into the things that are obviously the very most important thing to do do right now – you will end up doing the right thing every time, even if there is slightly less of it. 

It’s often been said that knowing what you should do is easy; it’s knowing what you shouldn’t do that’s hard.  If you repeatedly focus on and complete the one single thing you absolutely should do and do it well, it will be more readily clear what those things are you should not do. So, I guess ultimately, you have to choose: More features done less thoroughly with time spent on things that turn out to be a waste, or fewer, more complete features with fewer projects that you shouldn’t have done.

Flotsam and Jetsam #50

By Nick at November 23, 2011 03:32
Filed Under: Delphi, Flotsam and Jetsam, Software Development

Flotsam and Jetsam #49

By Nick at November 09, 2011 04:46
Filed Under: Software Development, Flotsam and Jetsam, Delphi
  • Hallvard Vassbotn has been sighted in the wild! Hallvard is an amazing developer and a great writer, and I’m delighted at the prospect of him starting to blog again, especially given his propensity to stretch Delphi language and RTL features to the limit.  Given all the new things that have happened in these areas since Hallvard’s last blog  post, one can only hope for really interesting stuff.
  • Fun to see people taking up the Dependency Inject mantle – here’s an article by Yanniel Alvarez Alfonso on a simple example of DI using DelphiDean Hill has a very good article about Software Flexibility that discusses how Dependency Injection can make your software more flexible and adaptable.   If my efforts have sparked an interest in Dependency Injection, I couldn’t be happier.  I’ll say it again:  If you aren’t using even the most basic form of Dependency Injection, then you are doing it wrong.
  • ninite.com is a really cool site that provides a valuable and helpful service.  It allows you to create a single install for a pretty broad and selectable collection of popular software.  This is particularly useful when setting up a new machine.  There’s always a million of these things that you want to install – Skype, Chrome, Firefox, your favorite IM client, media players, various utilities, etc. --  and Ninite.com allows you to select all of these and get a single installer for them all.  It does all the “smart” things that you want it to like get the 64-bit version if possible, ensures you have the latest versions -- and best of all -- it clicks all the “Next” buttons so you don’t have to.  Sweet.
  • I tweeted this notion this week -- “Crazy Idea of the Day: Every class that raises an exception unique to itself should have it's own exception type to raise. “ – and I thought that I’d expand a bit on it here.  One of my pet peeves is unclear error messages.  Somewhat of a corollary to that is the irritated feeling you get when an exception is raised, but you can’t tell right away where it came from. Thus was born the notion above – that if your class is raising an exception unique to itself (i.e., not something “normal” like EConvertError or EFileNotFoundException or something like that….) it should be raising an exception type defined specifically for the class itself.  This way, you can put a very descriptive error message in the exception, and the developer or user seeing the exception can know exactly where it came from. In addition, it allows anyone using  your class to easily trap exceptions specific to your classes.  I’ve been doing this for years, but have never seen anyone in the Delphi community really discuss it.
  • Every once and a while, I like to remind folks that they can go to the Delphi UserVoice page and vote for their favorite new features in Delphi.  This is totally unofficial, but it is interesting.  I’m still an admin there, so it’s always fun to mark items done as they get shipped. (I confess that it is also fun to close and/or reject requests that are……. not well thought out…?)  Currently, this item – “Better GUI separation and abstraction” -- is the top voted thing on the whole site, and I’m wondering if that really is indeed what the Delphi community wants the most.  In any event, you can certainly go there and vote and perhaps influence the future of the product. 

Getting Giddy with Dependency Injection and Delphi Spring #9 – One Interface, Many Implementations

By Nick at November 07, 2011 11:27
Filed Under: Delphi, Software Development

So far, we’ve been registering interfaces and implementations in a one-to-one relationship.  Each interface has one implementing class registered against it.  But what if you want to implement an interface many different ways, choosing which implementation to use depending on user input or other external factors?

As always, you can download the Delphi Spring Framework from GoogleCode.

Well, lucky for us, the Spring Container lets us do just that.  The Delphi Spring Framework container registration system allows you to specify a name for any giving implementation registration, thus distinguishing different registrations from on another, even if you register multiple implementers for the same interface. 

If you register multiple implementers for a given interface without specifying a name for each one, then the “last one in wins'”.

So, for instance, you might declare a simple credit card interface as follows:

type
  ICreditCard = interface
    ['{6490640C-0E2B-4F7D-908C-0E6A74DCC0A0}']
    function IsValid(aCreditCardNumber: string): boolean;
    function ChargeAmount(aCreditCardNumber: string; aAmount: Double): Boolean;
  end;

There are any number of credit cards that customers might want to use, so you’ll need to have credit card implementations for the various common vendors:

  GlobalContainer.RegisterType<TVisa>.Implements<ICreditCard>('VISA');
  GlobalContainer.RegisterType<TMasterCard>.Implements<ICreditCard>('MasterCard');
  GlobalContainer.RegisterType<TDiscover>.Implements<ICreditCard>('Discover');
  GlobalContainer.RegisterType<TAMEX>.Implements<ICreditCard>('AMEX');

This code registers four different classes (TVisa, TMasterCard, TDiscover, TAMEX) for the same interface (ICreditCard) via the string parameter on the GetService call.  Once these are registered, you can pick and choose whichever credit card processing class you want as the implementation of ICreditCard.  You can even change the selection at runtime based on, say, user input or different orders being processed, etc. 

For instance, if you have four radio buttons that allow the user to select one of four credit cards, you can do the following:

var
   CurrentCard: ICreditCard

...

procedure TMultipleImplementationsForm.RadioButton1Click(Sender: TObject);
begin
  CurrentCard := ServiceLocator.GetService<ICreditCard>('VISA');
end;

procedure TMultipleImplementationsForm.RadioButton2Click(Sender: TObject);
begin
  CurrentCard := ServiceLocator.GetService<ICreditCard>('MasterCard');
end;

procedure TMultipleImplementationsForm.RadioButton3Click(Sender: TObject);
begin
  CurrentCard := ServiceLocator.GetService<ICreditCard>('Discover');
end;

procedure TMultipleImplementationsForm.RadioButton4Click(Sender: TObject);
begin
  CurrentCard := ServiceLocator.GetService<ICreditCard>('AMEX');
end;

The above code will assign an instance of the appropriate implementing object to the single variable CurrentCard depending on which radio button the user selects.  The proper object is returned based upon the string parameter passed to the GetService call.  That string value, of course, corresponds to the object registered with that same string as shown above. 

Thus, you can register by name and then use as many implementing objects for a single interface as you want.   This is obviously very powerful, as you can choose from any number of implementations as well as add new implementations anytime you want.

A sample application showing this technique as well as some other interesting features can be found in the samples that come along with the Delphi Spring Framework

Fun Code of the Week #2

By Nick at November 07, 2011 06:51
Filed Under: Delphi, Fun Code, Software Development
function RandomString(aLength: Integer; aInputChars: string): string;
begin
  Result := '';
  if Length(aInputChars) <= 0 then
  begin
    Exit;
  end;
  Randomize;

  repeat
    Result := Result + aInputChars[Random(Length(aInputChars)) + 1];
  until (Length(Result) = aLength);
end;

Getting Giddy with Dependency Injection and Delphi Spring #8 – Miscellanea

By Nick at November 05, 2011 05:03
Filed Under: Delphi, Software Development

So far I’ve covered a much of the basics of Dependency Injection.  There’s a lot more to it, and plenty more to discuss, but for this article, I want to stop and discuss a few items that I have kind of glossed over.  So without further ado, here they are in my beloved bullet form:

  • I have been, as you’ve likely noticed, encouraging you to use interfaces when coding, and registering classes as implementing those interfaces with the framework.  What I think I failed to mention explicitly is that all interfaces registered with the Spring Framework have to have a GUID associated with them.  You can add a GUID any time you want into your code by pressing CTRL+SHIFT+G.  If you try to use an interface that doesn’t have a GUID, you’ll get this error:  “Project <projectname>.exe raised exception class ERegistrationException with message 'Non-Guid Interface Services are not supported.
  • If you’ve looked closely at the code in the demos, you might have noticed that before you can do anything with the Spring Container, you need to call GlobalContainer.Build;  This method needs to be called before you can get anything out of the ServiceLocator.  The Build method is the code that gathers up all the registered classes and either creates them or enable them to be created on demand, depending on the lifetime type that you have selected.  If you get the error 'LifetimeTypeManager was expected.' when you run your app, it likely means that you have faced to call Build on your container.  And in fact, the Build method is really the main purpose of your DI Container.  You should call Build once, and at the root of your application.  For Delphi developers, this means that it probably ought to be called as one of the very first things in the DPR file. This also means that you need to register your classes as early as possible as well.
  • You don’t have to use the Global Container and the Service Locator provided by the framework.  You are more than welcome to create your own and expose the functionality as you want.  What we have done here at Gateway Ticketing is to declare an interface that is a complete abstraction of the notion of a DI Container, and then implement the interface ourselves using a TContainer descendant from the Delphi Spring Framework.  That way, if the framework changes (and it has since we started) or if we even decide to use a different container, our code is completely decoupled from any particular implementation.  Just another great example of “Code against abstractions, not implementations.” Smile
  • I feel compelled to point out that the whole concept of a Service Locator is considered an “anti-pattern” by some. I haven’t come to a firm conclusion on this issue myself.  Yes, a Service Locator is almost always a Singleton, but I personally don’t view read-only singletons to be bad as do some.  (A read-write singleton is really a global variable, and I think we can all agree that global variables are the Spawn of Satan.) However, there appears to be some dispute as to whether the use of a container is indeed a Service Locator. Also, if all of your dependencies are defined before execution is available to the user, then is a Container really a variable at all?  It remains a matter of debate. Ultimately, I guess I view a Service Locator as so valuable and useful so as to out-weigh any of the drawbacks they might have. 
  • There is a weakness here -- and which gets to the previous point – in that things are actually so decoupled and late-binding is so explicit that it is indeed possible to get a successful build and not know that you forgot to register a needed implementing class until runtime.  And, in a complex system, it might be a long time before anyone notices that the implementing class for a seldom used interface is missing.  If you follow the pattern that I have shown of registering an implementation in the initialization section of a unit, then you must use that unit somewhere in your app to actually have the registration take place. And as mentioned, if you forget to add it, and don’t actually include that unit in your app, the compiler won’t tell you and you will only find out at runtime.  This is a weakness and you need to be very careful to ensure that you don’t fall into this trap.  Strategies might include a single unit for doing all of your registration, or some type of static analysis that ensures that every call to GetService has a corresponding RegisterService call (or whatever your methods are called).  Something to be aware of.

Those are just a few things that you might want to consider as you integrate Dependency Injection into your coding techniques. I’ve said it before, and I’ll say it again:  If you aren’t doing Dependency Injection, you're doing it wrong. 

Flotsam and Jetsam #48

By Nick at October 29, 2011 10:51
Filed Under: Delphi, Flotsam and Jetsam

Flotsam and Jetsam #47

By Nick at October 18, 2011 03:52
Filed Under: Delphi, Flotsam and Jetsam

Delphi Mocks: The Basics

By Nick at October 16, 2011 12:41
Filed Under: Software Development, Delphi, Unit Testing

Introduction

As you may have noticed, I’ve kind of started to become a championship caliber pain in the butt about unit testing.  I walk the halls of Gateway Ticketing saying “If your code isn’t easy to test, you are doing it wrong”.  I keep giving my Unit Testing presentation to anyone that will listen.  But I feel justified – unit testing is critical to writing clean, maintainable code.

One of the reasons people seem to frequently give for not doing unit testing is that “My code requires <some external dependency> and it’s too hard to configure for simple unit tests” or something like that.  Okay, fair enough.  I won’t point out how you should be using Dependency Injection to decouple that code and enable you to insert a mock or a stub or a different class for testing purposes.  (Okay, I lied – technically I guess I did mention that.  Sorry.)  But I get that sometimes implementing a complete, formal TMockXXXX version of your interface (and you are coding against interfaces and not implementations, right?) is not something you want to do. 

Mocks

In their simplest form, a mock object is simply an alternate implementation of a class that provides “fake” responses to method calls.  For example, you have a class TCustomer that has a method GetCustomerName, and normally, that call goes to the production database and gets the name (a simple, unlikely example, I know, but you get the idea).  So to avoid the call to the database, you just create TMockCustomer, and implement it’s call to GetCustomerName and have it return “George Jetson” every time.  This enables you to test the class that is using TCustomer without having to hit the database at all.

But that can get a bit clumsy.  What if you want to return different values based on different inputs?  What if you find a bug based on specific input or output, and you want to create a unit test for that specific case?  Then a mock class as described above gets harried, complicated, and hard to maintain.

Enter a Mocking Framework

What if we could have a framework that would allow us to implement any interface, and define easily and exactly what the inputs and outputs should be?  That would be cool.  This would enable you to easily create a mock object that can respond to method calls in defined ways in a flexible, easy to set up manner.  This is what a mocking framework does.

Obviously something this flexible needs some powerful language features.  Such a framework would have to be able to flex to dynamically implement an interface.  It would have to be able to dynamically recognize method calls and respond accordingly.  Fortunately, Delphi XE2 is up to the task.  Delphi XE2 introduces the TVirtualInterface class that lets you dynamically implement any interface at runtime.  Combine that with the new RTTI, and you have the ability to build a very powerful mocking framework.

And that is just what Vince Parrett of VSoft Technologies, author of the wonderful FinalBuilder, did.  He has built a very cool and very powerful library called Delphi Mocks and released it as open source for all of us.  Very cool – thanks, Vince.   Delphi Mocks is available on GitHub under the very developer friendly Apache 2.0 License.  Vince has written a nice “Getting Started” guide, but I wanted to write  this article to build a very simple example of a pretty simple use case for mock objects.  So let’s do that.

An Expensive Service

A typical use case for using a mock object is to replace a service that is “expensive”.  Sometimes that means expensive as in “actually costs money”, but it will more likely mean expensive in CPU cycles, database connectivity, or anything else that requires an external dependency that causes your class under test to stop being tested in isolation and start being integrated with something else.   Since a unit test should always test something atomically and leave nothing (database entries, files, charges on a credit card) lying around, any time that will happen when running a unit test, you probably should consider a stub or a mock object instead.

By “stub” I mean “a class that implements a particular interface but doesn’t really do anything”.  It’s not exactly the same as a mock object in that the interface in question will normally not return anything but merely do things external to the class.  A typical example is a logging class.  If you are running unit tests, you don’t want your logging system writing logs all over the place every time you run your tests, so you create a Logger stub class that acts like your regular logger, but which actually doesn’t do anything.  You can call it in your code, but you get nothing from it – which is what you want. 

So let’s look at a simple, but “expensive” service.  Consider the following code:

unit uCreditCardValidator;

interface

uses
      SysUtils;

type

  ICreditCardValidator = interface(IInvokable)
  ['{68553321-248C-4FD4-9881-C6B6B92B95AD}']
    function IsCreditCardValid(aCreditCardNumber: string): Boolean;
    procedure DoNotCallThisEver;
  end;

  TCreditCardValidator = class(TInterfacedObject, ICreditCardValidator)
    function IsCreditCardValid(aCreditCardNumber: string): Boolean;
    procedure DoNotCallThisEver;
  end;

implementation

uses
     Dialogs;

{ TAdder }

function TCreditCardValidator.IsCreditCardValid(aCreditCardNumber: string): Boolean;
begin
  // Let's pretend this calls a SOAP server that charges $0.25 everytim
  // you use it.

  // For Demo purposes, we'll have the card be invalid if it the number 7 in it
  Result := Pos('7', aCreditCardNumber) <= 0;

  ShowMessage('You were just charged $0.25');
end;

procedure TCreditCardValidator.DoNotCallThisEver;
begin
  // This one will charge the company $500!  We should never
  // call this!
end;

end.

This unit declares two things, an ICreditCardValidator and a class that implements it, TCreditCardValidator.  It simulates deciding a credit card is bad by saying any card number that has the number ‘7’ in it is bad.  Otherwise, any string will be acceptable. It’s a demo class, obviously, but it illustrates a class that would be used only in production, as you get charged by a credit card validating service every time you call IsCreditCardValid.    Clearly, you don’t want to be calling that whenever you run your tests.  Thus, it seems likely that any collection of unit tests that wants to use this service would likely want to use a mock class.

A Class to Use the ICreditCardValidator

Mock classes really become useful when you are testing a class that consumes an expensive service.  Thus, we’ll declare the following class, TCreditCardManager, which consumes ICreditCardValidator:

unit uCreditCardManager;

interface

uses
      uCreditCardValidator
    ;

type
  TCreditCardManager = class
  private
    FCCValidator: ICreditCardValidator;
  public
    constructor Create(aCCValidator: ICreditCardValidator);
    function CreditCardIsValid(aCCString: string): Boolean;
  end;

implementation

{ TAddingMachine }

function TCreditCardManager.CreditCardIsValid(aCCString: string): Boolean;
begin
  Result := FCCValidator.IsCreditCardValid(aCCString);
end;

constructor TCreditCardManager.Create(aCCValidator: ICreditCardValidator);
begin
  inherited Create;
  FCCValidator := aCCValidator;
end;

end.

This class is really simple – it just takes an ICreditCardValidator in it’s constructor and uses it to validate credit cards.  As a demo class it is really simple, but a more complete class would have methods to make payments against the card, etc.  But if, when testing this class, you pass it in an implementation of the ICreditCardValidator above, you’ll get charged $0.25 for every test you run.  That’s not something you’d really want to do, so this class seems like a good candidate for using a mock object to replace the implementation of ICreditCardValidator

Testing TCreditCardManager Can Be Expensive

So, the typical way to test TCreditCardManager might look like this:

procedure TestTCCValidator.TestValidateCreditCard;
var
  ReturnValue: Boolean;
  ExpensiveCCValidator: ICreditCardValidator;
  ValidCard: string;
  BadCard: string;
begin
  ExpensiveCCValidator := TCreditCardValidator.Create;
  FCCValidator := TCreditCardManager.Create(ExpensiveCCValidator);

  ValidCard := '1112221'; // Rule is that a bad card has a '7' in it
  BadCard   := '6667666'; // ..so this one is bad

  ReturnValue := FCCValidator.CreditCardIsValid(ValidCard);
  CheckTrue(ReturnValue);

  ReturnValue := FCCValidator.CreditCardIsValid(BadCard);
  CheckFalse(ReturnValue);
end;

However, if you run this in the GUI test runner for DUnit, you’ll see this:

image

 

And of course, if you keep this up, the bill you get will not make your boss happy.

Testing with a Mock

So, to avoid the wrath of your boss, you should create a mock object that behaves like you want it to but that doesn’t end up costing anything.  The first way you might do it is to create a new class that implements the ICreditCardValidator interface, but that does nothing or returns set values.  But that is kind of clunky, and hard to customize.  What you really want is what I mentioned earlier, an extensible mock that can be created an configured on the fly.  That’s where Delphi Mocks comes in.

The Delphi.Mocks.pas unit declares a type TMock which takes a parameterized type, and which then can sort of morph itself into an implementation of that interface using the cool new-to-XE2 class called TVirtualInterfaceTVirtualInterface basically allows you to implement an interface on the fly at runtime.  Thus, you can create a generic class (or record, in the case of TMock) that can appear to be any interface you want it to be. 

Thus, we can create a TMock that looks and acts like an ICreditCardValidator:

var
  CCMock: TMock<ICreditCardValidator>;
 begin
  CCMock := TMock<ICreditCardValidator>.Create;
  ...
end;

Once we have that mock, we can tell it how to behave:

  ValidCard := '1112221'; // Rule is that a bad card has a '7' in it
  BadCard   := '6667666'; // ..so this one is bad

  CCMock.Setup.WillReturn(True).When.IsCreditCardValid(ValidCard);
  CCMock.Setup.WillReturn(False).When.IsCreditCardValid(BadCard);

This code uses a nice fluent interface to be somewhat self-explanatory.  It basically sets the mock up as follows: “When I pass in the valid string, return True.  When I pass in the bad string, return False.”  This is a basic definition that will allow your TCreditCardManager class to exercise itself with both good and bad input, allowing you to test your code with both kinds of responses.  We can determine exactly what the inputs and outputs are and ensure that the mock displays the correct behavior and follows the business rules set out in the “real” implementation.  Notice, too, that the When call, through the delightful magic of generics, is actually an implementation of the ICreditCardValidator interface, and thus is able to execute a real method call to the method from that interface.  You even get support from Code Completion in the IDE. 

Now, you can create the Credit Card Manager, pass it your mock object, and run tests with your mock input and output:

  FCCValidator := TCreditCardManager.Create(CCMock);

  ReturnValue := FCCValidator.CreditCardIsValid(ValidCard);
  CheckTrue(ReturnValue);

  ReturnValue := FCCValidator.CreditCardIsValid(BadCard);
  CheckFalse(ReturnValue);

This way, you can exercise the instance and test it  to your hearts content without incurring any of the expense associated with your “regular” implementation.  If you need to add additional tests, you can simply tell the mock class what the new input and outputs are, and then run the appropriate tests.

Ensuring Code Is (or Is Not) Called

When writing tests, there may be times when you want to ensure that a given method is called with a frequency that you want to specify.  Thus, you can write things like:

  CCMock.Setup.Expect.AtLeastOnce.When.IsCreditCardValid(ValidCard);

  // Ensure that the tests never call this.  It costs $500!!
  CCMock.Setup.Expect.Never.When.DoNotCallThisEver;

And then, when all the test are run, call:

CCMock.Verify;

on the mock object, and it will validate that the calls that you required were indeed called. 

So, in the above example, if I were to call:

CCMock.Instance.DoNotCallThisEver;

I would get the following dialog:

image

…which of course tells me that I called a method in my tests that should not have ever been called.

There are also methods on the call to Expect interface that ensure that a certain call is made a minimum or maximum number of times, between a specified  number of times, at least or at most a certain number of times, and as we saw, even never.  Also, you can specify that one method be called before or after other methods.  This enables you to dictate exactly how your object methods are called, and what should or should not happen when you run your tests.

Conclusion

So the Delphi Mock library is a very powerful tool for making it easy to write concise unit tests that don’t connect to “expensive” classes that could make testing difficult.  The goal of writing testable code is a worthy one, and Delphi Mocks definitely can make it easier to reach that goal.

Getting Giddy with Dependency Injection and Delphi Spring #7 – Controlling Construction

By Nick at October 08, 2011 12:47
Filed Under: Software Development, Delphi

As always, you can download the Delphi Spring Framework from GoogleCode.

By now you should be getting the idea about dependency injection – how you can use it to decouple your code and provide instances of your objects.  Hopefully you see the benefits of coding against interfaces and not implementations.  And if things are going really well, you are writing unit tests with ease because your code is easily tested. 

However, I bet by now some of you are thinking that this looks really cool and all, but there is just a touch too much “magic” going on – that there is a bit too much going on under the covers.

Well, you are right about that – there is a lot going on under the covers.  The Delphi Spring Framework does a lot of work for you, mainly by creating instances of classes using Run-time Type Information (RTTI).  It controls the creation, and can even let you manage the lifetime of those objects.

But I also bet that some of you are a bit uncomfortable with the notion of relying on all that magic.  While turning over that control will work in many cases, you don’t always want to give up control over the  creation of your objects. 

Well, you don’t have to.  The framework allows you to customize the way that your classes are created if you so desire.  Very often, if your classes are well designed – your constructors are simple, you aren’t doing much more than assigning values – you don’t need to do anything special when you construct an instance.  But sometimes you do.  Sometimes, your class needs to be passed something dynamic – a class whose state can only be known at runtime.    For instance, you may have a given customer, and that customer has invoices, and you have a class that you want to pass that customer to, but you also want to completely decouple that class.  Your customer is dynamic – you may be running a query and need to perform this operation on every customer in your database. Or maybe the customer is doing something on your website, and so your customer object is specific to that customer.  In any event, the customer data is dynamic at runtime, and so the creation of an object can’t be cookie-cutter.  It has to be unique each time you need an instance of this object that takes action on the given customer. 

The code below comes from the Samples directory of the Delphi Spring Framework.  It’s part of the Demo.Spring.DelegatedConstructor project

The Spring Framework lets you control the creation of your objects through a method on the TRegistration class – the class used to register types against interfaces.  As part of registering your class, you can pass an anonymous method of type TActivatorDelegate, which his declared as:

TActivatorDelegate<T: class> = reference to function: T;

The TRegistration class uses the fluent interface, so you can chain together a number of things that you want to attach to any given registration.  So, for instance, if you have a project involving a TUser class, and the TUser class is dynamic, then a class (such as TUpgradeUser) which needs a TUser, might be registered as follows:

  GlobalContainer.RegisterType<TUserProcessor>.Implements<IUserUpgrader>.AsTransient.DelegateTo(
    function: TUserProcessor
    begin
      Result := TUserProcessor.Create(GetCurrentUser);
    end
  );

The TUserProcessor class is registered as implementing the IUserUpgrader interface.  The lifetime of the resulting class is set to be “Transient” meaning that the implementing class will live “normally”; that is, it will be destroyed when the interface reference goes out of scope.  (Note that AsTransient is the default lifetime.  We’ll discuss container lifetime management in a future blog post). 

Finally, the actual creation of the TUserProcessor class is “delegated to” an anonymous method – a function in this case, as noted above – that simply returns an instance of the TUserProcessor class.  The key here, of course, is that the anonymous method can call the GetCurrentUser routine which will inject the current, dynamic TUser instance into the resulting object.  You can do anything you want in this anonymous method, including creating and setting up the resulting object in any manner you choose.  You could set properties and even call methods on the resulting, implementing object. 

If you examine the code for the project, you’ll note, of course, that it doesn’t actually do anything other than write to the console.  The GetCurrentUser call is merely a singleton returning the same instance of TUser.   The code is merely illustrative, and so the “background stuff” doesn’t really do anything.  In a real application, a call to GetCurrentUser would do just that, return an instance of TUser that represented the current, dynamic state of the user in question.   The critical part to note is that you can control the creation of the TUserProcessor to as large a degree as you want. 

Finally, when you actually call the ServiceLocator to grab an instance, the Container will call your anonymous method and return an instance constructed exactly like you want it to be constructed.

So in the end, the Spring Container gives you total control – if you want it – over the creation of your objects.  If you need to, you can have a little control over the “magic” that takes place and sprinkle your own little fairy dust on the construction process.

Fun Code of the Week #1

By Nick at October 06, 2011 11:20
Filed Under: Delphi, Fun Code
unit uIsPalindrome;

interface

function IsPalindrome(const aString: string): Boolean;

implementation

uses
       Spring.Collections
     , {$IF CompilerVersion >= 230}System.{$IFEND}SysUtils
     ;

function CleanString(const aString: string): string;
var
  C: char;
begin
  // Remove all non-alpha chars and make all lower case
  // Spaces don't matter, so let's count only letters
  Result := '';
  for C in LowerCase(aString) do
  begin
    if CharInSet(C, ['a'..'z', 'A'..'Z']) then
    begin
      Result := Result + C;
    end;
  end;
end;

function IsPalindrome(const aString: string): Boolean;
var
  Stack: IStack<Char>;
  C: Char;
  NoSpaces: string;
  Temp: string;
begin
  NoSpaces :=  CleanString(aString);

  Stack := TCollections.CreateStack<Char>;
  for C in NoSpaces do
  begin
    Stack.Push(C);
  end;
  Temp := '';
  repeat
    Temp := Temp + Stack.Pop;
  until Stack.Count = 0;
  Result := Temp = NoSpaces;
end;

end.

Added: I always enjoy posting code like this. Note that it is entitled "Fun Code", not "Highly optimized, perfectly written Code". ;-)

Flotsam and Jetsam #46

By Nick at October 05, 2011 13:58
Filed Under: Delphi, Flotsam and Jetsam
  • I will be speaking this year at CodeRage 6.  I’m giving two talks, one on Dependency Injection, and one on Unit Testing.  Please attend.  I think my talks in particular will be really good.  But maybe not as good as all the other stuff you can learn there
  • Are you aware of the fact that FireMonkey, RAD Studio, and Delphi all have spanking new pages on Facebook?  I wasn’t.  And they do.
  • Holy crap!  Allen Bauer is alive!
  • I’ve been trying to write some more example applications for the Delphi Spring Framework, and so I was researching the Factory Pattern to see if I could find a good illustration to build an example for (TFoo and TBar can only take you so far….) and I ran across a nice article on MSDN that describes it nicely.  It actually has a nice example of a “Computer Factory”, and I’ll likely riff of that to create a “real world” example of a physical object.  But the part that caught my notice, and caused me to write this entry was a quote at the beginning:  “When was the last time someone asked the designers of the Empire State building to add ten new floors at the bottom, put a pool on the top, and have all of this done before Monday morning?” And the answer, of course, is “never”.  Winking smile  Anyway, it just was another data point in my ongoing contention that software developers are not engineers. 
  • This is a pretty amazing and thorough tutorial on LiveBindings.  Live Bindings is one of those cool features that I need to learn about and that appears to be cool now, with the potential to get a lot cooler in the future.

My Book

A Pithy Quote for You

"A people that values its privileges above its principles soon loses both."    –  Dwight D. Eisenhower

Amazon Gift Cards

General Disclaimer

The views I express here are entirely my own and not necessarily those of any other rational person or organization.  However, I strongly recommend that you agree with pretty much everything I say because, well, I'm right.  Most of the time. Except when I'm not, in which case, you shouldn't agree with me.