Background

Previously I wrote a bit about singletons. I’m not afraid to say that I think singletons have a time and a place… Okay, I’m afraid to say it, but it’s actually how I feel 🙂 After learning more and more about inversion of control design patterns and programming by interfaces, I started to notice just how inflexible singletons are. When you consider using a singleton, you should be considering both the pros and cons without jumping right into it. Here’s an example of my approach for mixing singletons, programming by interfaces, and a bit of inversion of control.

The Setup

I’m actually surprised you got this far. I’m sure you’re probably just sticking around to see how messed up this could possibly be. I’m actually proud that this little pattern has worked out so well when I’ve used it, so it can’t possibly be that bad.

One major drawback to singletons is that they are often implemented as concrete classes. That is, you ask some class X for it’s instance (via a static property/method) and it provides you it. This doesn’t mix very well with programming by interfaces. So, the first step is to have your singleton return an interface instead of a concrete class. Unfortunately, this on it’s own only provides a few benefits, and it’s really only a minor abstraction layer. You can change your singleton class around all you want, but the only dependencies people are going to see are what’s exposed on the interface. As long as your interface isn’t changing, you’re in a good position. With this change alone, we’ve managed to tackle a bit on programming by interfaces, which makes me just a bit happier.

So, what’s the problem now then? Well, now that I have my singleton returning an interface, the unfortunate truth is it’s always going to be the same class backing that interface. It’s incredibly risky if I start putting some sort of logic in my singleton’s property to get the instance that will return different references that could implement the interface. I mean, once your code is running, you want to make sure you’re always getting the same reference back… or else you’re not using a singleton! The drawback to this is that it completely ruins inversion of control and dependency injection!

An Example

Consider that I have a singleton that has information about my application. (If you don’t like my example, then you’ll surely hate using WinForms, because Microsoft does it with their Application class. So, it’s a fair example!) Okay, so if we pretend that we need something just like the Application class in our project, we might create some interface IApplication and create a singleton that returns an instance of an IApplication.

Suppose in one implementation we have, we really want to be using reflection and the assembly information to figure out our application’s information. Our concrete class would implement the IApplication interface but the methods would revolve around using reflection and querying the assembly for what it wants. If we built up a whole framework that used this singleton… We’d be tied to that implementation!

What happens if we go to make another application that wants to use this same framework, but it needs to be able to provide the application information through a configuration file? Well… We’d be pooched! Our singleton that’s used everywhere (and yes, please continue crying about the use of the singleton… Just remember Microsoft’s Application class) and we can’t really do anything about it!

Or can we?

The “Solution”

Okay, so here we are. I’ve demonstrated the problem with a scenario that isn’t too far fetched. How do we fix this crappy situation we’ve got ourselves in by using the dreaded singleton pattern? We use my other best friend: events. Except we use them in a way that makes me cringe. Static events.

So, if you were to run the program, what outputs would you expect in either case? What happens when you forget to set your event handler? What happens when you set your event handler and don’t provide a type? What if it’s a bad type?

Summary

I’m not claiming this is the best approach to solve this problem, and I’m not even encouraging that everyone go ahead and use it. Some of the pros of this are:

Advantages of programming by interfaces! You’re only exposing interface definitions to others.

Easy to use. Just hook up your type to a event handler when your program initializes.

Some of the cons are:

All the things people hate about singletons. All of them.

Static events are absolutely hideous.

You’re giving some other class control of creating your singleton instance.

There is no compile time checking or contracts for how your singleton needs to be created.

And now that you know some of the good and some of the bad, can you leverage a design like this? You can check out a working solution I put together for the code and example I described above over at Google Code. Hope you were able to learn something (either good or bad)!

Background

I previously wrote about why I like to use events here and here. I figured it would be appropriate to illustrate a simple case where you can delegate decisions between functionally separate parts of code (say, between an application layer and a presentation layer). If you’re well versed in C# and .NET, this might put you to sleep. If you have no idea what I’m talking about, hopefully this will help. By the end of this, hopefully you’ll have a better idea for how you can use an EventHandler to pass data/state back through an invoked event… And don’t forget to check out the code!

The Scenario

Let’s assume we have a layered application, which is usually my go to. I might have three layers: one for data persistence, one for my business logic and one for interacting with the user. I’ll call these the data, application, and presentation layers, respectively. Let’s also assume that the dependency flow works from the top layer down (so presentation layer depends on application and data, and application depends on data). Nice.

In my application layer, I have a class that can process data. Specifically, it can capitalize an input string and spit out the capitalized output. However, some input characters are not letters A-Z or a-z… So how should our processor behave? Let’s have it delegate this decision to the user (who interacts with the presentation layer) and get back our result.

The Workflow

The following is the workflow for the application:

Create a processor object

Hook on the event handler so that the presentation layer can handle the corresponding event

Start processing the input

Capitalize valid characters

When we reach an invalid character…

Call our data processor’s event to delegate the work to anyone who can make the decision for us (in this case, our presentation layer)

Have the event handler (the presentation layer) ask the user if we should skip the input

Store the result back on the event args

Back in the processor class, based on the result of the event args, we can skip or add the character.

Summary

It’s a pretty straight forward task really. Because event args are objects in C#, we can store state on them and pass them around easily. If they were value types, we’d have to rely on function calls to return the user’s decision as to whether or not we should skip the input. In my opinion, this is a bit uglier (but certainly still doable).

I’ve created a sample project and hosted it at Google Code, here. Check it out!

Background

Previously, I wrote about how events provide you with flexibility in your code. If you take on an event-based paradigm, you can view your system as a group of components that have events execute when certain conditions are met, and less of a procedural view where X always must occur after Y. But what else do events let us do? Decouple your architecture! We all know decoupling is a beautiful thing, so let’s see how it’s done.

How Events Decouple Your Code

So the big question then is, how? I’d like to start by providing framing an example architecture. If we assume that we have code that is decoupled by major functionality, we might have some sort of layered architecture. This could mean that we have three layers: presentation, application, and data. These layers would be responsible for user interaction, core business logic, and data storage/retrieval respectively. Let us also assume that the knowledge of layers flows from the top down. In our example, the data layer knows only of itself, the application layer knows about itself and the data layer, and the presentation layer has access to all three. It’s essentially just the flow of dependencies. Great. So where is this going?

If you’ve structured the various components in your system to take advantage of events, C# events provide us with a pretty awesome signature: you get the sender of the event, and a little magical parcel of data called EventArgs. Now let’s recall that in my previous posting, I mention that an event is really just a type of delegate. What does it mean to delegate? Literally, what does it mean? The great Google tells me: “Entrust (a task or responsibility) to another person, typically one who is less senior than oneself”. There. The secret of decoupling. My code can’t take responsibility for doing something, so I should tell whoever is interested that now might be a great time to do something.

Let’s See An Example!

Let’s continue off of the sample architecture that I already started off with. So we have our three layers. Let’s pretend we have some sort of import process where we read in lines of a file. Every line in the file is supposed to have two values, separated by a comma. This is all done by an importer class in our data later. Sounds easy.

Now, I’m not suggesting this is something you’d actually want in your application, it’s simply to demonstrate my point. So let’s pretend that the source of our data could sometimes be poorly formatted. Our import function can easily know about this (i.e. it splits the line on a comma, and finds out that there are not exactly two values). But does it know how to resolve it? Is it supposed to skip it? Is it supposed to magically figure out how fix it? Does it crash and burn? Wait… Maybe it’s not responsible for making that decision… So who is?

Invoke that event! If your importer class has an event, let’s say, LineFormatError, then someone on the outside can subscribe to it. Maybe my presentation layer can subscribe to it and, through event args, tell the invoker of the event (my importer class reference, of course) how to handle it. The flow could look something like this:

Hook your necessary events up, so something in the presentation layer hooks on to my importer’s event for line format errors.

Start your import.

Upon hitting a poorly formatted line, invoke the LineFormatError event.

The presentation layer receives the event (so now we’re in the “event handler”).

The presentation layer could use information provided in the event args to ask the user if they want to skip the line.

Based on the user’s decision, the presentation layer sets some information on the event arguments that says whether or not to skip it.

The control goes back to the data layer where it checks the event args for what to do–skip or abort.

How is this decoupled? Well, quite simply, you don’t have your data layer directly showing message boxes to the user to decide what to do. It has absolutely no idea that there’s even a message box being shown… it doesn’t care! It simply agrees that it’s not responsible for making the decision of whether or not to skip or abort, but let’s someone else handle it. It delegates the decision through an event.

Summary

Events are beautiful things. Leverage them, and you can take advantage of some really decoupled code. Your various components often can’t be responsible for certain tasks, but using events, these components can delegate the decisions to other parts of your code that are certainly responsible for making the decision.

Background

As a developer, there’s often a point when you’re tasked to build something that’s a key part of the architecture of your software. Maybe it’s not a key component to the all of the application, but it’s pretty foundational at least for a part of the application. Often we put our thinking caps on, plan a bit of what we’re about to code, and then dive right into it. If you do TDD, you might go start coding your tests but regardless of your approach, you’re likely going to start coding some classes pretty soon and forget completely about the use of an interface.

You shouldn’t.

Start With Interfaces

In my opinion, if you’re writing code that’s part of your application’s foundation, you should start with interfaces. If you’re already rolling your eyes and whining to yourself that now you’re going to have to code some class and then have some interface that just redefines the methods and bloats your code, then take a deep breathe. Her’es my reasoning:

The interface defines what goes in and out of your class. If you’re only looking at this, you’ll see how other developers have to interact with your class.

If others can extend your work, you offer a lot more flexibility by providing an interface than forcing them to implement a concrete class.

There’s this fancy programming topic called Inversion of Control that you can make happen a lot easier just by starting with interfaces first, and you might need something like it down the road.

Interfaces are excellent for your layered architectures.

It’s not a big list so maybe you actually go through that on your one deep breathe I told you to take. Maybe the tremendous code bloat of adding a few method signatures in a file has you so upset already that you can’t even focus on what I just said. That’s okay, you can always come back and try again once you’ve calmed down.

How Others Interact

The interface defines the exposed parts of what your class will implement. If you already have trouble making classes and trying to guess at what to make public/internal/protected/private, this might help you out. Whatever you put in your interface must be visible to others outside of your class because interface implementations have public members. All your other functions you wanted to implement? You start to think “Well… maybe this would be useful outside of this class…”. But now the question is, how useful? If it’s that useful, then is it foundational enough to be part of the interface? If not, it should probably be scoped to the class and not outside of the class.

If you read my post on what makes a good API, I touch on a lot of the great points for interfaces. You probably still don’t think this warrants the several line code bloat. Hang in there.

Extending Your Work

So you have your whole API set up like a bauss now. You think it’s all fine and dandy because it gets the job done and passes all the tests. Awesome. But it’s only awesome today. Tomorrow someone needs to extend your work. Someone wants to provide their own object into your code as a parameter now, let’s say. Here’s the signature that you wrote:

void CoolestFunctionEver(MyConcreteClass input);

You weren’t wrong by being excited that everything works. You should te proud about that–congrats. But now if I want to provide my own input to your function, I have to go extend your class like this:

public NicksConcreteClass : MyConcreteClass
{
// all the good stuff inside here
}

Which may not seem that bad… but if I had another class that existed and already had most (if not all) of the information and functionality, I essentially have to duplicate it or create some sort of copy constructor to make it work. If you had done this with your original method signature and been thinking of interfaces:

void CoolestFunctionEver(IMyInterface input);

Then the world would be a better place. I could use my existing class, implement your interface, and just pop my reference right in there as a parameter. No need to add any duct tape or glue to make it work. It just works nicely.

If you don’t see the value to this already, I would argue that you may not have written enough code in large projects. That’s not meant to sound like a jerk or anything, but this is not an unusual scenario and unfortunately leads to more code bloat than defining an interface would have.

Invert That Control

If you haven’t heard of this, it will seriously open your eyes to some better code design. Inversion of Control (IoC) lets others “inject” their own classes and dependencies into your existing code. The only way to get this working nicely is if you have interfaces.

If your functions are operating on concrete classes, that means they depend on those concrete classes. Dependencies lead to coupling and code that isn’t very extensible. You may not have seen scenarios where this can come up, but let me try to provide an example.

Let’s pretend we have a layered application with a presentation layer, application layer, and a data layer. Suppose we have our entire application working and we have a MySQL based model in our data layer. Everything is great. One day, someone comes along and says “MySQL has been working great for our customers, but in order to penetrate this other market segment, our users need to be able to use SQLite”. (Okay, maybe this is a little contrived but still…) You think to yourself “No problem! We aren’t using anything fancy from MySQL so implementing SQLite is going to be 5 minutes of work!”. But then you realize it… Everywhere that accesses your data layer uses the MySQL model class that was created. Everywhere does it. You need to be able to use either though, so you can’t even just replace it with all with the SQLite model you’re about to create. Uh oh.

If interfaces were used from the beginning, this would have been a walk in the park. Literally if you have one near the office, because it would have been a 5 minute fix leaving you tons of time for a stroll. If all of the code referencing models instead referenced a nice clean model interface, say, IModel then you could “inject” your new model. In the few areas where you actually go to initialize your concrete model class, you could add the logic to do MySQL or SQLite and then everywhere else just sees it as an IModel. They actually have no idea what the underlying implementation does, and they don’t care!

This point alone, in my opinion, is worth the “code bloat” of your interface definition. It could save you hours and the cost of a bottle of Advil.

Layers on Layers on Layers

This point kind of ties in with the IoC points and my points on extending your work. If you have a layered architecture, then you need to split up your code into pieces that are functionally different. Your presentation layer is responsible for rending things and making them pretty for user interaction. Your application layer does the heavy lifting, and your data layer does all that low level stuff nobody wants to think about 🙂

Interfaces help to provide a nice layer of abstraction. If you declare your class that implements your interface in some other project or want to move it’s definition between layers, this won’t really have any affect on the code relying on the interface so long as the interface definition doesn’t move.

Why is this good? Well, to exaggerate my point, let’s pretend someone is an absolute beauty and decides to implement your amazing data model in… your presentation layer. Great. Okay so despite it being in the wrong location, it works, and it works real well. If your data model interface resides in the correct spot and everyone is using the interface, then it’s minimal work to move your data model class to the right spot. Cut it out, move it to the correct project/layer, and change the one/couple spot(s) that initializes the reference. All of that code that references the interface can go absolutely untouched. Talk about bauss mode refactoring. You just moved the bulk of your data layer between projects and across layers and didn’t have to worry about breaking much code.

Summary

If you still aren’t convinced, then I suppose I did a poor job explaining all of this. Leveraging interfaces in your code helps to ensure a flexible and decoupled architecture… And you can’t really ask for much more than that. If you’re concerned with adding a a file here and there to contain some signatures because you think it’s going to bloat your code base, you’re probably the guy/girl trying to compress all your code into one line. In which case, you should have started here.

Background

My position at work allows me a bit of freedom in how I code and more importantly, influence how others code. I was recently having a conversation with a colleague about what I think makes a good API, from a high level. The context of our discussion was pertaining to developing a C# based API, but this really applies to any object oriented API.

I had two key points that I wanted to address, and while they’re not the only important things, I believe they’re often overlooked. The first thing is how people will use your API, so how they will call methods and use the results. The second point was about how people will implement your API should they want to extend your work and implement their own classes. Here’s what I was trying to drive home:

Usage:

As a programmer, when you use an API, you want it to be simple. If you’re using preexisting concrete classes, you want the methods to be easy to call and you want the results of those methods to be useful. How do you achieve this when making an API? Well, my guidelines are:

Make your inputs to the method as generic as possible

Make your return values as information-packed as possible

Simple right? If your inputs are generic enough, you can pass all sorts of things in. For example, if your function takes in a ReadOnlyCollection, this function wouldn’t necessarily be as easy to use as one that takes only an IEnumerable. If it’s not obvious, it’s because IEnumerable is a far more generic type. With an IEnumerable, I can pass in an array, a list, a queue, a stack, or any collection. I can pass in anything that implements IEnumerable! Conversely, if I require a ReadOnlyCollection, all of my callers who may have these other various types of collections need to do some conversion to make it a ReadOnlyCollection.

To the second point, you want as much information as you can get when calling a function. It’s almost the exact same argument as for parameters, but it works the opposite way. Consider if I have a function that returns an IEnumerable. That means that for anyone that calls my function, all they’ll have access to is something they can enumerate over to get string values. Okay, that’s not too bad… But what if realistically everyone who calls your method really needs a list of strings? What if the common way to use your method is to get the IEnumerable result of your function, create a list out of it, and then add a few more items. Your API has basically created the additional step of requiring callers to create a list out of your return value. So… Why not just return a list? This is a lot more obvious if you look at your concrete implementation and notice that you likely do use something like a list (or some other concrete collection) when doing work inside the function. Why return something that’s harder to use?

Implementation:

The flip side to all of this is how other developers will implement the interfaces (or extend the classes) you provide in your API. And guess what? All of the arguments I just made for simplifying the life of the caller are essentially inverted for people implementing interfaces in your API.

If my interface calls for an IEnumerable to be passed in, then the only thing I can do is enumerate over it. Maybe in my own implementation this works fine… but what if someone else implementing your interface would benefit greatly from having a list? What if they can make an awesome optimization by knowing how many items are in the collection or by checking to see the if the 100th item is a particular value? Well, they can only enumerate, so this becomes difficult.

As for return types, before I argued that for the caller, returning as much information as possible is great. Consider this example. If in my API I managed to create a custom collection class that has all sorts of awesome metadata. Just to make up something completely random, let’s pretend I have a class for collections of integers and I have all these fancy properties on it that tell me the Mean/Median/Mode. The caller would say that’s awesome! Sweet! So much information returned to me just by calling this simple function! However, the implementer of your interface is now thinking, “Oh crap… First you restrict my inputs to something super basic and then I have to somehow return that fancy object?! How the heck am I going to do that?!”

Summary:

To summarize what I wrote here, I think a good guideline for API’s comes down to:

Making inputs generic enough to ease the life of the caller and provide just enough information to the implementer of the method.

Make return values as information-packed as possible without placing the burden of creating complex classes (and adding dependencies) to the implementer of the method.

Simple right? If your API is designed such that others will not be extending it (and it’s really only people calling your methods) then you can completely bias your design in favour of the caller!

I work as a team lead of software engineering at Magnet Forensics (http://www.magnetforensics.com). I'm into powerlifting, bodybuilding, and blogging about leadership/development topics over at http://www.devleader.ca.