Posts with ""

SOLID - The D is for Dependency Inversion Principle

Wed, 02 Jan 2013 10:35:43 +0100

The fifth principle of the five SOLID principles is the Dependency Inversion Principle (DIP). You might expect an article on the ISP first, but I feel the internet is filled with enough posts about SOLID. This one was already finished so I'll publish it nonetheless :)

The DIP deals with avoiding mixing different levels of abstraction in your code. In this article we will explore the last of these principles in depth.

As for the previous four, Robert C. Martin took the time to summarize the Dependency Inversion Principle for us:

1. High level modules should not depend upon low level modules. Both should depend upon abstractions.

2. Abstractions should not depend upon details. Details should depend upon abstractions.

Let's look at an example to clarify this:

function storeBike()
{
    $Bike = getBikeInformationFromPostRequest();
    writeBikeToMySQLi($Bike);
}

function getBikeInformationFromPostRequest()
{
    //parse $_POST and return a Bike object
}

function writeBikeToMySQLi(Bike $Bike)
{
    //store $Bike in a new MySQLi record
}

Of course this code is extremely trivial but we have managed to create a two line function (storeBike) with an algorithm that is absolutely not reusable. Why is it not reusable? Because a high level action (store a Bike) depends upon two low level actions: parse a request into bike information and save bike information to MySQL.

If you want to read from something else than $_POST or save to something else than MySQL you have to rewrite the algorithm. Although our algorithm is small and trivial it would be 100% reusable in other cases if the code was refactored to this:

interface BikeReader
{
    public function read();
}

interface BikeWriter()
{
    public function write(Bike $Bike);
}

function storeBike(BikeReader $Reader, BikeWriter $Writer)
{
    $Bike = $Reader->read();
    $Writer->write($Bike);
}

The new code works becuase the high level store function now only depends on abstractions. The same function could be used for reading bikes from a file and write them to output as long as the used BikeReader and BikeWriter implement the interfaces.

A more tangible example

I want to show you how depending on abstractions makes our lives easier in a larger example. Since we're going to be loading, updating and storing bikes a lot in our application I would like an Api for that. It would not be such a good idea to write the same queries or perform the same validation over and over.

In the following example there are two interfaces, one for bike and one for a repository. These are the abstractions details can depend on. Of course we need a detail as well, this will be our Api. This Api is where the logic is! Validation, logging, event triggering, you name it. This is what desperately needs to be tested in every application out there!

Lets have a look at our first interface:

interface Bike
{
    /**
     * @return int
     */
    public function getId();

    /**
     * @return string 
     */
    public function getName();

    /**
     * @param int $id
     */
    public function setId($id);

    /**
     * @param string $name
     */
    public function setName($name)

}

The second interface we need is for a class that is able to perform CRUD-like operations on bikes, a repository:

interface BikeRepository
{
    /**
     * @return int 
     */
    public function create();

    /**
     * @param int $bikeId
     * @return Bike
     */
    public function retrieve($bikeId)

    /**
     * @param Bike $Bike
     * @return bool
     */
    public function update(Bike $Bike);

    /**
     * @param Bike $Bike
     * @return bool
     */
    public function delete(Bike $Bike);
}

Now that we have defined our abstractions we can have a look at our detail. Again, this is where the logic is! For readability I only show a possible update function:

class BikeApi
{
    private $Repository;

    public function __construct(BikeRepository $Repository)
    {
        $this->Repository = $Repository;
    }

    /**
     * @param Bike $Bike
     * @return bool
     */
    public function update(Bike $Bike)
    {
        $name = $Bike->getName();
        $id = $Bike->getId();

        if (empty($name) || empty($id)) {
            return false;
        }

        if ( ! $this->BikeRepository->update($Bike) ) {
            return false;
        }
        
        return true;
    }
}

What did we gain?

Now why did we go to all that trouble of defining interfaces and injecting objects into our BikeApi?

It allows us to change implementation details of one detail without affecting another detail.

The repository that is used by the Bike Api can store the Bike data however it wants to. The business logic is completely detached from the implementation detail of our data storage. Changing the way we store data is a relatively small problem that has no effect outside repositories. As long as the new solution implements the existing interface we even know for sure that our application will keep working (tests remember!).

Confusion with dependency injection

Dependency inversion is often confused with dependency injection. While they touch similar grounds they are not the same. Dependency inversion is described in the two rules at the very start of this article. Dependency injection is a means to an end.

We enable dependency inversion by injecting the Repository into the constructor instead of calling new SomeImplementationOfRepository() inside the Api. With the "new call" we tie the Api to a specific implementation, with the typehinted constructor injection we don't.

This brings a second advantage. Since the repository is injected and the interface is type hinted we can replace it with a mock object based on that interface in our tests. This allows us to test the business logic in complete seperation of the rest of the system, which is all we really want to. You can see how easy testing the Api in isolation of the repository is in the two sample tests for the Api below:

class BikeApiTest
{
    public function testUpdate_whenBikeNameIsNotSet_shouldReturnFalse()
    {
        $RepositoryStub = $this
            ->getMockBuilder('BikeRepository')
            ->getMock();
        
        $BikeStub = $this
            ->getMockBuilder('Bike')
            ->getMock();
        $BikeStub
            ->expects($this->any())  
            ->method('getName')
            ->will($this->returnValue(false));

        $BikeApi = new BikeApi($RepositoryStub);
        $result = $BikeApi->update($BikeStub);

        $this->assertFalse($result); 
    }

    public function testUpdate_whenBikeRepositoryUpdateFails_shouldReturnFalse()
    {
        $RepositoryStub = $this
            ->getMockBuilder('BikeRepository')
            ->getMock();
        $RepositoryStub = $this
            ->expects($this->any())
            ->method('update')
            ->will($this->returnValue(false));
        
        // Make sure the update does not return false to early by setting up a
        // Bike that does return values for name and id.
        $BikeStub = $this
            ->getMockBuilder('Bike')
            ->getMock();
        $BikeStub
            ->expects($this->any())  
            ->method('getName')
            ->will($this->returnValue('name'));
        $BikeStub
            ->expects($this->any())  
            ->method('getId')
            ->will($this->returnValue('id'));

        $BikeApi = new BikeApi($RepositoryStub);
        $result = $BikeApi->update($BikeStub);

        $this->assertFalse($result); 
    }
}

Conclusion

By separating details from other details and writing software that only knows about other parts through interfaces we can create software that enables us to change implementation of parts without breaking or changing other parts. As an added bonus, this decoupling of parts allows us to unit test our code. Don't be afraid of code that others might find java-esque if it makes refactoring easier and your test suite larger!

Tags: SOLID, architecture, OOP, PHP

Continuous learning

Fri, 21 Dec 2012 10:03:39 +0100

A couple of years ago I was still at the Utrecht University of Applied Science (university in short from now on), I detested it. Sure, I liked information science and I like to dabble around, but formal education is something that was obviously not for me. It took me four different educations and a year of working in between to even finish one.

Although I finished with a decent average of an 8 ( a B in letters I guess) I didn't even enjoy the education I finished (Information Sciences). I'm quite sure the education didn't quite enjoy me either. The fun part of all this? Ever since I finished my Bachelor of Science I started doing exactly what that same education had been trying to get me to do all this time: learning.

For a long time I didn't even know if information science was my cup of tea. Dabbling in PHP and playing some games is something else than full-time programming. Official education didn't exactly convince me either. The moment I knew I was going to be a programmer was during my first internship (most Dutch universities of applied science have an internship lasting somewhere between a couple of months up to half a year). Suddenly I was building stuff that mattered and went directly to production. The speed at which I was learning, by doing, was astronomical as compared to what I was learning at the university.

I think there where two things that made up the difference:

At the university I did not create meaningful things. I've, quite literally, built a couple of "employment agency systems". The idea was that by building a system you learned a new technique, say JDeveloper, Java in general, Java on the web with JSP's and whatnot, etc. Each time something new arrived, a new simplified meaningless system was built. We built to learn. At my current position I learn to build. I mean this both ways, I am learning stuff so I can build software and I'm learning to build software in general. The difference is astonishing. Switch two words and all of a sudden I like this thing called learning!
At the university I learned stuff when someone decided it was necessary. I therefore learned a lot about different techniques and tools I will never ever even consider to use. Currently I am learning what I need to learn right now. My attention goes 100% to learning stuff that will be directly useful to me, the current project and the company.

Some nuance is required...

Of course I spend time learning stuff that is not directly related to my current position. Lately I've tried to be more or less active developing Saffire. I haven't put in weeks of work, but every now and then I do something. Which forces me to understand C. Now I will never use C at my current position, but it helps me understand PHP better. It makes me understand a different level of programming languages. I'm convinced this makes me a better programmer in the long run.

Also, I do understand some stuff needs to be taught. You simply need to understand syntax, datastructures and basic algorithms. But if you like your education because you're doing something useful there, I'm convinced one is bound to be interested even in such static knowledge transfer.

I think it would be great if during your education you would build something that was actually used. According to this article 5.202 students finished their higher education in the field of information science in 2012 in the Netherlands alone. Why can't they build something? Open source software, the university student management system, grade systems, whatever. Tutor students while learning skills on an actual project. To teach the virtue of testing, let them refactor old code and provide tests for it. Why wouldn't you use an actual project to learn about database normalisation? If you really want to teach students to create websites in java, at least make sure the site is going live...

I understand this is a massive undertaking that requires a lot of work from both universities, students, open source projects and other included parties. It will probably remain a lone rant on just on of the many blogs that is hosted on the internet. Still, I like the idea so I get to rant about it :)

P.S.

This blog was originally going to be something along the lines of the following:

Khan Academy is brilliant. I never received formal math education, but using Khan Academy I can still learn about algebra, geometry and trigonometry at my own pace and on my own level. Just because I like learning. Khan Academy rocks: https://www.khanacademy.org/

But then I realised the above post and switched topics. Khan Academy is brilliant though!

Tags: random, opinion

SOLID - The L is for Liskov Substitution Principle

Tue, 04 Sep 2012 09:01:50 +0200

Between a holiday in the states, buying and redecorating a house and a summer it has been a long time since my last blog entry. It seems about time for a new one :) Today we'll be dealing with the third principle of SOLID, the Liskov Substitution Principle.

The Liskov Substitution Principle (LSP) was coined by Barbara Liskov as early as 1987. The principle is very tightly connected to the earlier discussed Open Closed Principle. A good way of adhering to the OCP is understanding and implementing code that uses the Liskov Substitution Principle. In this article we will discover why and how.

Barbara Liskov described the Liskov Substitution Principle as follows in 1988:

What is wanted here is something like the following substitution property: If for each object O1 of type S there is an object O2 of type T such that for all programs P deﬁned in terms of T, the behavior of P is unchanged when O1 is substituted for O2 then S is a subtype of T

Wow.

That's a mouthfull, so lets replace the letters with something more understandable (Note: Raleigh is a UK-base bike manufacturer).

RaleighBike is a subtype of Bike if: "for each object of type RaleigBike there is an object of type Bike and a program that is defined in terms of Bikes does not change its behaviour when Bikes are substituted with RaleighBikes".

Still a mouthfull. This is how Robert C. Martin summarized it:

Functions that use pointers or references to base classes must be able to use Objects of derived classes without knowing it.

Finally something that is understandable. And if you've read the previous article on the Open Closed Principle, it should sound somewhat familiar. If you read back the article than the quote above is almost what we accomplished with our code to output the current stock of a bike:

foreach ($bikes as $Bike) {
    $API = BikeAPIFactory::getBikeAPI($Bike);
    echo $API->getCurrentStock();
}

If you haven't read the OCP article, here is a small recap for you. To avoid numerous switch statements to different kind of API calls for different brands of bikes, we decided to give each bike brand its own API that had exactly the same function signatures as the others. In the end a factory is used to decide which API should be used for a specific bike object.

But we have to deal with the trustworthyness of our API's. We expect them to all implement getCurrentStock, but no one is telling them. If the API's are a little like me, they might not implement that method untill they're told to ;) Also we have no common base to reference to (think type hinting in function signatures for instance).

Design against abstractions

API's are just like us humans, if we don't impose some rules, there will be hell to pay. So lets come up with some rules. We can do this by defining an interface or abstract class. Since the Bike API's all have in common that they receive a Bike and store it in their constructor, I feel it would make sense to make an abstract class out of it, but lets show both:

interface BikeAPI
{
    public function __construct(Bike $Bike);

    public function getCurrentStock();
}

abstract class BikeAPI
{
    private $Bike;

    public function __construct(Bike $Bike)
    {
        $this->Bike = $Bike;
    }

    abstract public function getCurrentStock();
}

Our API's can now either extend the abstract class or implement the interface (choose one though!), in both cases we have ensured that each of our API methods is present and has the same input parameters.

It seems like we are well on our way of adhering to the Liskov Substution Principle. After all, no code using a RaleighBikeApi object needs to know that it is dealing with a RaleighBikeApi as long as the RaleighBikeApi is a subclass of our parent BikeApi. Right?

Wrong!

The signatures of the BikeAPI methods are set now, so the input will not change. There is no way to create an API that does not take a Bike in its constructor for instance.

But what about return values? There are no rules for return values in the interface nor in the abstract class. We could add some comments with return value hints, but they would be exactly that: hints.

Design by contract

When reading up on the LSP you will soon come accross Bertrand Meyer's name and the term Design by contract. This is a programming methodology that defines contracts to ensure (amongst others) a classes's:

input and return variables
preconditions
postconditions

You can see where this touches the LSP. A subclass that changes the return variable for instance, can not be used in algorithm as if it was its parent. If we expect the getCurrentStock to return an array with info and one subclass starts returning a CurrentStock object (with stock for multiple warehouses for instance) we are in trouble. We solved this problem for input variables, but we can not force our API's to do the same for output variables. This means we need to have conventions in our development team.

This convention would be the LSP. A subclass may not change input our output, it must not change pre- or postconditions and it should leave the state of invariants as they are. This is something programmers will have to start doing, there is no syntax (at least not in PHP) to enforce it, but it is very important when you want to write code that adheres to the Open Closed Principle.

Some rulebreaking

Let's look at a small example where the LSP is violated to see what kind of problems it will cause. Gazelle (a dutch bike manufacturer) has started offering a new service. They don't return the total stock for all their warehouses anymore, instead they return the individual stock per warehouse, so customers can estimate delivery times. If a programmer notices this and wants to use this in a single location we are starting to get into trouble. If he starts refactoring to incorporate the new information in the return value without paying attention to the fact that he is violating the LSP, the code will start to fail on us:

class GazelleAPI extends BikeAPI
{
    public function getCurrentStock()
    {
        //parse response for stock per warehouse location
        return array(
            'dutchWarehouse' => $dutchWarehouse,
            'germanWarehouse' => $germanWarehouse,
        );
    }
}

When running (hopefully) the unit test suite before committing this change, the developer will soon notice that his change is going to cause trouble. All Api calls should return the same kind of information. At a minimum they must all return arrays but it would probably be for the better if the returned some sort of stock object. Right now, unit tests fail and users get presented with the word array instead of the actual stock.

Conclusion

Validating the LSP automatically is not that easy in PHP. There are languages built around the Design by contract paradigm (Eiffel by Bertrand Meyer for one), but PHP is not. There is a PEAR project that adds functionality for design by contract though.

However I feel something else is more important. Robert C. Martin writes in his article:

A model, viewed in isolation, can not be meaningfully validated. The validity of a model can only be expressed in terms of its clients.

And that is exactly it. It might seem perfectly valid to change the output of a function, certainly in cases that are less obvious than the one above. But if you don't look at the system, the software using the component you just changed, all kind of problems may arise. By now it must be clear that adhering to the Open Closed Principle is impossible without the Liskov Substitution Principle.

Tags: PHP, SOLID, architecture, OOP