Posts tagged with: principles

SOLID principles with real world examples

The following article aims to explain the five SOLID principles with real world examples. The SOLID principles are five programming principles which is considered to be the foundation of every well designed application. Following the principles will most likely lead to applications which are is easy to extend and maintain. That’s possible since you got small well defined classes with clear contracts.

All motivator images are created by Derick Baley.

Let’s get started with the principles.

Single Responsibility Principle

Single responsibility states that every class should only have one reason to change. A typical example is an user management class. When you for instance create a new user you’ll most likely send an welcome email. That’s two reasons to change: To do something with the account management and to change the emailing procedure. A better way would be to generate some kind of event from the account management class which is subscribed by a UserEmailService that does the actual email handling.

The most effective way to break applications it to create GOD classes. That is classes that keeps track of a lot of information and have several responsibilities. One code change will most likely affect other parts of the class and therefore indirectly all other classes that uses it. That in turn leads to an even bigger maintenance mess since no one dares to do any changes other than adding new functionality to it.

Making sure that a class has a single responsibility makes it per default also easier to see what it does and how you can extend/improve it.

Classes that are hard to unit test are often breaking SRP.

External links

* Wikipedia
* Example & tips on how to follow the principle (earlier post by me)

Open/Closed principle

Open/Closed principle says that a class should be open for extension but closed for modification. Which means that you can add new features through inheritance but should not change the existing classes (other than bug fixes).

The reason is that if you modify a class, you’ll likely break the API/Contract of the class which means that the classes that depend on it might fail when you do so. If you instead inherit the class to add new features, the base contract is untouched and it’s unlikely that dependent classes will fail.

Example violation

Here is a real world parser method (from a SO question which I’ve answered):

    public void Parse()
    {
        StringReader reader = new StringReader(scriptTextToProcess);
        StringBuilder scope = new StringBuilder();
        string line = reader.ReadLine();
        while (line != null)
        {
            switch (line[0])
            {
                case '$':
                    // Process the entire "line" as a variable, 
                    // i.e. add it to a collection of KeyValuePair.
                    AddToVariables(line);
                    break;
                case '!':
                    // Depending of what comes after the '!' character, 
                    // process the entire "scope" and/or the command in "line".
                    if (line == "!execute")
                        ExecuteScope(scope);
                    else if (line.StartsWith("!custom_command"))
                        RunCustomCommand(line, scope);
                    else if (line == "!single_line_directive")
                        ProcessDirective(line);
    
                    scope = new StringBuilder();
                    break;
    
                default:
                    // No processing directive, i.e. add the "line" 
                    // to the current scope.
                    scope.Append(line);
                    break;
            }
    
            line = reader.ReadLine();
        }
    }

It works great. But the method have to be changed each time we want to add support for a new directive. It’s therefore not closed for modification.

Solution

Lets create an interface which is used for each handler (for '$' and '!' in the example above):

    public interface IMyHandler
    {
        void Process(IProcessContext context, string line);
    }

Notice that we include a context object. This is quite important. If we create a new parser called SuperCoolParser in the future we can let it create and pass a SuperAwsomeContext to all handlers. New handlers which supports that context can use it while others stick with the basic implementation.

We comply with Liskovs Substitution Principle and doesn’t have to change the IMyHandler.Process signature (and therefore keeping it closed for modification) when we add new features later on.

The parser itself is implemented as:

    public class Parser
    {
        private Dictionary<char, IMyHandler> _handlers = new Dictionary<char, IMyHandler>();
        private IMyHandler _defaultHandler;
    
        public void Add(char controlCharacter, IMyHandler handler)
        {
            _handlers.Add(controlCharacter, handler);
        }
    
        private void Parse(TextReader reader)
        {
            StringBuilder scope = new StringBuilder();
            IProcessContext context = null; // create your context here.
    
            string line = reader.ReadLine();
            while (line != null)
            {
                IMyHandler handler = null;
                if (!_handlers.TryGetValue(line[0], out handler))
                    handler = _defaultHandler;
    
                handler.Process(context, line);
    
    
                line = reader.ReadLine();
            }
        }
    }

If you go back and look at the ! handling you’ll see a lot of if statements. That method likely have to be changed to add support for more features. Hence it do also violate the principle. Let’s refactor again.

    public interface ICommandHandler
    {
        void Handle(ICommandContext context, string commandName, string[] arguments);
    }
    
    public class CommandService : IMyHandler
    {
        public void Add(string commandName, ICommandHandler handler) 
        {
        }
    
        public void Handle(IProcessContext context, string line)
        {
           // first word on the line is the command, all other words are arguments.
           // split the string properly
    
           // then find the corrext command handler and invoke it.
           // take the result and add it to the `IProcessContext`
        }
    }

External links

* Wikipedia

Liskovs Substitution Principle

Liskovs Substitution Principle states that any method that takes class X as a parameter must be able to work with any subclasses of X.

The principle makes sure that every class follows the contract defined by its parent class. If the class Car has a method called Break it’s vital that all subclasses breaks when the Break method is invoked. Imagine the suprise if Break() in a Ferrari only works if the switch ChickenMode is activated.

Violation

Let’s use the motivator image as inspiration and define the following classes:

    public interface IDuck
    {
       void Swim();
    }
    public class Duck : IDuck
    {
       public void Swim()
       {
          //do something to swim
       }
    }
    public class ElectricDuck : IDuck
    {
       public void Swim()
       {
          if (!IsTurnedOn)
            return;
    
          //swim logic  
       }
    }

And the calling code:

    void MakeDuckSwim(IDuck duck)
    {
        duck.Swim();
    }

As you can see, there are two examples of ducks. One regular duck and one electric duck.

The electric duck can only swim if it’s turned on.The MakeDuckSwim method will not work if a duck is electric and not turned on.

That breaks LSP since any user of the IDuck interface expects the duck to swim when calling MakeDuckSwim.

Solution

You can of course solve it by doing something like this (in the method that uses the ducks)

    void MakeDuckSwim(IDuck duck)
    {
        if (duck is ElectricDuck)
            ((ElectricDuck)duck).TurnOn();
        duck.Swim();
    }

But that would break Open/Closed principle and has to be implemented everywhere that the ducks are used (and therefore still generate instable code).

The proper solution would be to automatically turn on the duck in the Swim method and by doing so make the electric duck behave exactly as defined by the IDuck interface.

    public class ElectricDuck : IDuck
    {
       public void Swim()
       {
          if (!IsTurnedOn)
            TurnOnDuck();
    
          //swim logic  
       }
    }

External links

* Wikipedia

Interface Segregation Principle

ISP states that interfaces that have become “fat” (like god classes) should be split into several interfaces. Large interfaces makes it harder to extend smaller parts of the system.

There is nothing that says that there should be a one-to-one mapping between classes and interfaces. It’s in fact much better if you can create several smaller interfaces instead (depends on the class though).

Violation

The MembershipProvider in ASP.NET is a classical example of a violation. MSDN contains a large article (which 4 out of 34 have found useful) which contains a long and detailed instruction on how to properly implement the class.

Solution

The provider could have been divided in several parts:

* MembershipProvider – A facade to the below interfaces
* IAccountRepository – Used to fetch/load accounts
* IPasswordValidator – Checks that the password is valid (according to business rules)
* IPasswordStrategy – How to store PW (hash it, use encryption or just store it in plain text)

Now you only have to implement a small part if you need to customize the provider (for instance IAccountRepository if you are using a custom data source). There’s a saying: “Favor composition over inheritance” which the membership providers illustrates well. The original solution used inheritance while mine used composition.

External Links

* Wikipedia

Dependency Inversion Principle

The principle which is easiest to understand. DIP states that you should let the caller create the dependencies instead of letting the class itself create the dependencies. Hence inverting the dependency control (from letting the class control them to letting the caller control them).

Before

    public class Volvo
    {
        B20 _engine;

        public Volvo()
        {
           _engine = new B20();
        }
    }

After

    public class Volvo
    {
        IEngine _engine;

        public Volvo(IEngine engine)
        {
           if (engine == null) throw new ArgumentNullException("engine");
           _engine = engine;
        }
    }

Which makes it a lot more fun since we now can do the following:

    var myVolvo = new Volvo(new BigBadV12());

(Nice real world example, huh? ;))

Update

I messed up a bit. Dependency Inversion states that you should depend upon abstractions and that lower layers should not be aware of higher layers. I’ll get back to that. Dependency Injection is when you inject dependencies into the constructors instead of creating them in the class. Inversion Of Control is that the container controls your objects and their lifetime.

A. HIGH LEVEL MODULES SHOULD NOT DEPEND UPON LOW LEVEL MODULES. BOTH SHOULD DEPEND UPON ABSTRACTIONS.
B. ABSTRACTIONS SHOULD NOT DEPEND UPON DETAILS. DETAILS SHOULD DEPEND UPON ABSTRACTIONS

The original principle targets modules while I also like to apply it at class level too. It makes the principle easier to apply (so the text below is how I apply the principle).

Depend on abstractions simply means that you should depend on as generic class/interface as possible. For instance IUserRepository instead of DbUserRepository or HttpRequestBase instead of HttpRequest. The purpose is that your code should be as flexible as possible. The more abstract the dependencies are, the easier it is to refactor them or create new implementations.

Depending on abstractions also make your code less likely to change if the dependency change.

External links

* Wikipedia
* Introduction

Summary

Feel free to leave a comment if something is unclear. It will not just help you, but all future readers.


Single Responsibility Prinicple

SRP is one of the easiest principles to learn, but one of the hardest to master. The reason to this is that it can be quite hard to see if a method or class breaks SRP or not. I got a few simple rules that will help you check if you are breaking the principle.

First of all, lets check the definition of SRP:

every object should have a single responsibility, and that responsibility should be entirely encapsulated by the class

Hence my interpretation varies a bit from the original statement, as I like to apply it to classes, methods and interfaces. If you do not agree: Go buy an ice-cream, eat it, put a smile on your face and continue reading.

XmlDoc is an excellent tool if you use it correctly. So many users abuse it and screams out to the world their product/library/etc has DOCUMENTATION! The DoXZ! yay! What they fail to mention is that the documentation is simply a reflection of the methods and classes. Read my other blog posts to get a few tips on how to write good documentation. Back to SRP. Documentation can be a tool for SRP too. If you find yourself using AND’s when describing a method, class or an method argument you have most likely broken SRP. Refactor.

When talking about SRP it’s important to know what is meant with single responsibility. When it comes to methods, they should only contain logic for one type of responsibility. Here is a small example:

public class UserService
{
     public void Register(string email, string password)
     {
          if (!email.Contains("@"))
              throw new ValidationException("Email is not an email!");

         var user = new User(email, password);
         _database.Save(user);

         _smtpClient.Send(new MailMessage("mysite@nowhere.com", email){Subject="HEllo fool!"});
     }
}

The name Register suggests that the method should register the user in the system. Doing email validation doesn’t seem to belong in an register method. Let’s break it out into a new method.

public class UserService
{
     public void Register(string email, string password)
     {
          if (!ValidateEmail(email))
              throw new ValidationException("Email is not an email!");

         var user = new User(email, password);
         _database.Save(user);

         _smtpClient.Send(new MailMessage("mysite@nowhere.com", email){Subject="HEllo fool!"});
     }

     public bool ValidateEmail(string email)
     {
         return email.Contains("@");
     }
}

One might wonder why that line of code should be moved. It’s so small. In reality email validation might be larger, but that’s not really important. Following SRP usually makes it easier to follow DRY (Don’t repeat yourself) too, since you make methods smaller and let them solve a specific problem. Hence it’s a lot easier to reuse code.

If we continue to look at the method we’ll see that it also sends an email and is therefore also responsible of delivering the email. Lets move that to a new method too.

public class UserService
{
     public void Register(string email, string password)
     {
          if (!ValidateEmail(email))
              throw new ValidationException("Email is not an email!");

         var user = new User(email, password);
         _database.Save(user);

         SendEmail(new MailMessage("mysite@nowhere.com", email){Subject="HEllo fool!"});
     }

     public virtual bool ValidateEmail(string email)
     {
         return email.Contains("@");
     }

     public bool SendEmail(MailMessage message)
     {
         _smtpClient.Send(message);
     }
}

omg! We did it again. A single line method. Is this sh!t really necessary? Yep, it is. When the application grows you’ll see that you might want some templating. By using a separate method you could replace commonly used macros like #SITEURL#, #PRODUCTNAME# etc in that method instead of duplicating the code in each method that wants to send an email.

Now it’s time to move on and look at the class. Do it follow the SRP? Do it? Nooo, don’t try to fool me. I got some NINJA zkillz. promise! SendEmail and ValidateEmail has nothing to do with a class named UserService. Let’s refactor.


public class UserService
{
     EmailService _emailService;

     public UserService(EmailService emailService)
     {
         _emailService = emailService;
     }
     public void Register(string email, string password)
     {
          if (!_emailService.ValidateEmail(email))
              throw new ValidationException("Email is not an email!");

         var user = new User(email, password);
         _database.Save(user);

         emailService.SendEmail(new MailMessage("mysite@nowhere.com", email){Subject="HEllo fool!"});
     }
}

public class EmailService
{
     public bool virtual ValidateEmail(string email)
     {
         return email.Contains("@");
     }

     public bool SendEmail(MailMessage message)
     {
         _smtpClient.Send(message);
     }
}

Actually I’m unsure of if the ValidateEmail method belongs in the EmailService class. What do you think? Leave a comment.

SRP is nothing that you do once. It’s something that you should keep doing during all types of development (like when writing new code and when you maintain existing one).

Summary

Try to follow the following rules to get a hang of SRP:

  1. Document your code. Using AND’s should make you check your code again.
  2. You should be able to associate all method names with the class/interface name. (A method called ValidateEmail cannot be associated with a class called UserService)
  3. A method should only contain logic that can be associated with the method name.

DRY KISS, SR!

omg! wtf?! Nahh, this ain’t a porn blog. The title is three coding principles that I try to follow when I code. And this blog is going to be all about them.

You’ll find code refactorings, insights and such that I discover during my days as a software architect/developer.

As you might notice, no entries will be elaborate or poetic. They will be short and concise: HARDCORE!

DRY – Don’t repeat yourself.

Most of you have probably heard of this principle. You can read more about it at wikipedia.

Code duplication is evil since you:

  1. can get the same bug in a lot of different places
  2. refactoring becomes hard (try finding all the places you have the duplicate code in)
  3. larger programs -> more code to maintain
  4. your application design is most likely bad as a rotten apple

Let’s focus on the last entry. Sorry, but it’s true. If you need to duplicate code, you have done something wrong. Go and take a coffee. Go through your code and try to refactor it. Ask a colleague of yours. DO NOT CONTINUE UNTIL YOU SOLVE THE PROBLEM. Trust me. You’ll regret it later.

KISS – Keep it simple (and) stupid

I have a really active brain. It comes up with all sorts of cool stuff and solutions when programming. That’s a BIG problem when coding. Coding is not about having the coolest solution or the most fancy features. It’s about doing as little as possible to get the job done. I do not mean that you should take shortcuts or writing shit code. I’m talking about doing a simple solid solution which get’s the job done but nothing more.

Time estimation is still one of the hardest thing to do when developing software. How long have we been coding? 40 years? And we still can’t do proper time estimations. El oh el! Do you know why? Because most programmers do not keep it simple! We love to learn new stuff and do cool solutions.

Finish the application first! Then do the fancy stuff.

Read more about KISS at wikipedia.

SR – Single responsibility

Have you ever seen a cop (Mr. Police) mow a lawn when on active duty? (If you have, please give him this link). I thought not. Why? Because doing a lot of different things would make him a bad cop. It’s the same with your classes, methods and projects. Don’t let a class both fetch the users from the database and present the info to the user. Do not let a method both send an email and eject the CD tray.

If a class is called UserReporsitory it should not do anything else than fetch/save you users from/to your data source. That’s what single responsibility means.

Why?! you ask. Well, letting your method/class/project doing a lot of stuff will make it hard to understand what your application does. It will also make it harder to understand. But the most important thing is: It will make it hard to test your application. (unit tests). And you don’t want that. Unit tests are a life saver when your application grows. All those green dots that says that the tests have passed will give you a warm fuzzy feeling inside when your application is 5M lines long. Imagine how hard it would be to test an app that large when all your classes do a lot of different stuff. Imaging a cop mow a lawn.

Read more about single responsibility @ objectmentor || oodesign

That’s it

Again. Welcome to my blog. Leave a comment or two.