Tech Team Cancer

Hi guys

I keep promising that I will be posting frequently, and then life happens. I will continue my posts and tutorials and trying to share and disseminate things I’m learning or have learned over the course of my career.

I’m incredibly lucky, not only do I have my own experiences and exposures to draw upon when trying to make decisions, but I have a number of friends in development, from starting their careers right through to development managers and such. Of course, it would be unfair for me to take all of the credit for the things I’ve learned along the way, and at some point in the near future I might post a list of people I’ve learned from, but it will be a long list; and it would be wholly unfair for me to miss anybody crucial out of that list. It’s been a long career so far and I’ve met a lot of people.

Anyway, today I want to cover a topic that’s quite close to my heart. I received a huge compliment the other day from a long time friend of mine, Oliver Sarfas, he was saying that he has just picked up a piece of software I’d developed. Now I want to throw some context into this, I first met Oliver when I was only a couple of years into my career. We have stayed in touch the whole time, but were professionally reunited at my last role.

This particular piece of software, it’s fair to say, is quite complicated in its structure; in that very little is hardcoded anywhere. I was taking a matrix of equations and building them into a data structure, running them against years of legacy data as a rule by which to calculate some financial information. In terms of fluidity and flexibility it’s one of the most complicated bits of software I’ve built. It had a feature or two that I didn’t get to finish before leaving for my current role.

Anyway, Oliver was tasked with finishing up the project by building some of the functionality I didn’t get chance to do. He sent me an email, the long and short of this email was a thank you for writing code using industry standard techniques and leaving decent documentation. I can only presume following PSR-2, known design patterns, and decent naming conventions played some part of this.

This really conveniently brings me to the point of this post:

Tech Team Cancer

It sounds like a really horrible thing to refer to, but truthfully the things I am about to describe are cancerous. I’m not pointing at any of my previous roles here, everyone does at least one of the things on the list, some companies are better than others, but generally, these things help kill tech teams:

1. Not Leaving Documentation (Ivory Towering)

There is nothing worse than finding yourself having to work on a project you know nothing about, that has no code comments or documentation attached.

One thing I would like to say on this, however, is code comments are great tips for a developer. But code comments document that piece of code, that module, that class. They don’t document the over-arching design or principles of the piece of software.

Documentation is essential in other developer’s being able to work on your software.

2. Not Following Patterns

This is a bit of a weird one. Using known design patterns, and principles, and everything else does help your code’s maintainability. But what I really mean here is being consistent, across all of your code (really it should be across all of your team’s projects). Any convention is better than no convention.

If you have a piece of software and you name all of your classes following PSR-2 standards and your namespaces follow PSR-4, great! Get everything else consistent too, table and field names are a really common one for this.

3. Not Knowing When You’re Out Of Your Depth

This is another seriously fluid one. Any time you are out of your depth is bad. It doesn’t matter the context. Don’t fully understand the specification, don’t fully understand what they’re aiming to gain, or the use case, for this software, don’t understand the technologies you’re using. Any of these things lead you to build bad software.

What usually happens, in my experience, is that you, for want of a better phrase, blag it. Blagging, in development, is terrible. It means you don’t have a plan, if you don’t have a plan how can you have a coherent software design and accompanying principles?

If you have none of those things you’re destined to end up with spaghetti code, indecipherable nonsense and, as you learn more about what you’re supposed to be doing, horrendous shoe-horning to make functionality work.

The big problem with this one is that if you fall foul of it you will definitely fall foul of the other points here as well.

4. Bad Commit Messages

We’ve all been in that position where we’re asked to fix a bug on an existing piece of software. Fair enough. And then we look at the code, and all we can say or think (depending on your personality) is “Oh for ****s sake, what the **** was that **** thinking?! Seriously why the **** would you do that?” and this usually lasts for a few hours, before resigning yourself to shoe-horning in the resolution or stating it has to be rebuilt.

This is where a decent commit message goes a long way, and a code comment. If I have to do something a bit nasty, dirty or something that would get my immortal soul cussed out once I’ve left the office, I leave a code comment and a commit message; keeping professional but saying something like “This is a workaround for requirement X which was introduced after the original specification; if you change it Y will happen and you will also need to check Z” – because that’s the kind of information I would like to find if I were inheriting the maintenance of that code.

A good commit message is the difference between “Why the hell did you every hire X? He didn’t know what he was doing!” to “Ah, right. I see why he did that, it sucks, but I get it”.

5. Relying on Tribal Knowledge

This one is so much more dangerous than it sounds. When you build something, or when you fix an issue. This one isn’t just for developers either, testers, client facing staff and project staff are all guilty of this (usually). If you know something about a project or a piece of infrastructure it really does need to be written somewhere.

Take this real world example. I was working on a large and complex project which was business critical for the company that I was working for at the time. We were nearing the end. Luckily I keep documentation and code comments pretty up to date and always communicate how I’m working on. Unfortunately one Friday afternoon, I’m on my way home from work, all is good, we’re ahead of schedule and everything is great with regards to the project.

Then I’m on my way home, hit oil and come off of my motorbike. I go rolling up the A14 in Cambridgeshire, breaking and dislocating my shoulder and snapping my thumb. That’s me unable to drive for about 12 weeks in total. I was really lucky, firstly I didn’t die. Secondly, I used to work part remotely, so was able, within a couple of days and a makeshift injury-friendly work space, to get working again.

Imagine if it were worse, or if I couldn’t have worked remotely. The company I was working for would’ve been right up the creek without a paddle.

In Summary

To summarise this article. The main problems any development team, whether growing or shrinking, young or old, is information and sharing it.

Whether you’re sharing it through documentation, code comments and git commit messages. Or however you’re sharing it. Whether than information is software design, client facing, client requirement, anything at all. If ever there is a piece of information that you, and you alone, have you need to find a way to share it; otherwise you really are asking for something to go wrong with no conceivable disaster recovery available.

From procedural to object orientated, a tutorial

Hi there everyone

Something I’m often faced with, having lots of friends with varying degrees of programming experience, is how do (PHP) developers move from sub 25k roles to the higher end of the spectrum, the 35-60k developer roles.

Generally, in my experience, the are some key differences in the salary expectations and the skills you can expect for a developer demanding those salaries. These can be broadly summed up as below:

  • True understanding of object orientated programming
  • Knowledge and application of programming principles
  • Exposure to multiple technologies and ability to move around within them
  • Web application development vs website development (the difference between relying on browsers and being able to do things like offloading, queueing, sharding, true separation of concerns, performance optimisation, caching, all that stuff)

To this end I’ve had a decent number of developers ask me how to start working with classes, and work in an object oriented way. So I thought I would do a tutorial on this. I’m going to cover some design patterns, some PHP functionality and various other things.

This is going to be a long and wordy tutorial, but hopefully what it will do is give you some understanding in the differences between procedural and OO programming.

All code samples are available in this project on my GitHub

Step One: The Hardest Part

The first thing I am going to disclaim is simple: Please do not try to have a half procedural, half OOP project or system. It’s going to be an absolute nightmare to maintain!

Now that’s out of the way, let’s talk about some design basics. Avoid god classes! A god class is a class which has many, many responsibilities, it can do everything. In terms of a practical application of a God class think of an ecommerce system: if a single class is responsible for checking stock, adding items to your basket, emptying your basket, and the checkout process – it has far too much responsibility.

I always think it’s a good idea to follow the Single Responsibility Principle – to those new to this I simple explain it as follows:

A class should be responsible for a single job. If you can’t tell me, in a sentence, what it does; then it is almost definitely doing too much.

As such if you have a requirement for an ecommerce system as defined above, checking stock levels would be it’s own class. The point of this is so that:

  1. The class can be used throughout your project, anywhere that you need to check stock levels
  2. The class can be modified and know that all stock checking functionality happens through a single place
  3. Any business logic can be contained in a single place
  4. The class could be swapped out if needs be, again you know all functionality is encapsulated here

Encapsulation: Goes hand in hand with “DRY” (don’t repeat yourself). Basically bringing everything to do with a certain concern (i.e. stock checking) into a single place, rather than leaving it scattered throughout your code.

So you now have a basic idea of what you use a class for, and in what scenarios you would create a new class – basically, any time you need to get something done.

Now working with objects, as opposed to working with a bunch of variables, has some real perks.

NB: Throughout this article I am going to refer to “classes” and “objects”. For all intents and purposes a class is defined, an object is instantiated. Therefore my User class, once it physically exists, becomes an object, until that point it is a class.

If I have an “Order” object rather than a whole heap of variables or a massive multi-dimensional array, I can put functionality in there which I need, I can do decisions and logic based on information contained within that order. What you’re doing is neatly organising everything into it’s own compartments within your code.

The user may be hitting a button to “add to cart”, but in practice you might be doing all kinds of things; checking the stock level, applying voucher codes, modifying the stock level, calculating the value of the cart so far, all sorts. So this separation becomes invaluable.

However, the point of this part of the article is simple. It’s going to be really difficult to follow, and make almost no sense, to have a bunch of objects floating around a procedural execution. The reason for this is, again, simple; if you have some stuff procedural, and some wrapped in classes and objects; how the heck could I possibly know where to look?

Learning Point Two: Using and understanding the syntax

In this point we’re going to cover some basic concepts:

  1. Inheritance – abstracting and extending classes
  2. Interfaces – implementation and usages
  3. Properties, Methods, Privacy and Scope

Firstly, one of the beautiful things about classes is inheritance. Let’s take a basic example of a User. A User might be a Guest, a Member, a Moderator and an Administrator; but they almost definitely share a bunch of common functionalities, like having a user ID for example (though a guest’s would be 0 or null). You don’t want to have to write a whole heap of code to get the user ID a bunch of times, when it’s the same functionality. You want all of your different types of users to share this functionality, this is where inheritance comes in.

Inheritance

<?php

abstract class User
{
    protected $userId = 0;
    protected $isLoggedIn = true;
    protected $isStaff = false;
    public function getUserId()
    {
        return $this->userId;
    }
    public function isLoggedIn()
    {
        return $this->isLoggedIn;
    }
}

class Guest extends User
{
    protected $isLoggedIn = false;
}

class Member extends User{}

class Moderator extends Member
{
    protected $isStaff = true;
    public function hasPermission($permission)
    {
        // Some logic here and return TRUE or FALSE
    }
}

class Administrator extends Moderator
{
    public function hasPermission($permission)
    {
        return true; // Administrators can do anything
    }
}

See in GitHub

The handy thing about this is that everyone is a User. So if ever I try to manage some dependency and state that a User is required as an object, I can do this really easily, because everything extends off of User, or one of its derivatives.

Also everyone from Guest to Administrator has a getUserId method, which is quite handy and an isLoggedIn method, so it doesn’t matter if my factory returns me a Guest or an Administrator, the functionality is going to work.

Just to clarify some bits here. Guest::isLoggedIn is false, but Member::isLoggedIn (and everyone who extends Member, or Moderator) returns true. Moderator::isStaff returns true as does Administrator::isStaff (because of the inheritance).

Site note: You could never do: $user = new User(); Because User is defined as an abstract class, as such you could do $administrator = new Administrator(); (or any of the other classes)

Interfaces

An interface is, the best way I’ve heard it described, is the difference between plugging a socket into the wall, vs having to wire in your lamp by hand. You can define an interface on an object, to ensure it conforms to certain standards, basic example now of an Emailable interface.

This interface ensures that the entity, whatever it is (User, Customer, Employee, Organisation, Website) can be emailed, by specifying it must have some methods available to it.

In this example we can make anything we want emailable, by simply adding the methods defined and stating that this class implements the interface – now we can send an email to the fridge if we wish, as long as it can define those methods!

<?php

interface Emailable
{
    public function getRecipientName();
    public function getEmailAddress();
    public function acceptsHtmlEmail();
}

class Client implements Emailable
{
    public function getRecipientName()
    {
        return 'Very Important Company Plc';
    }
    public function getEmailAddress()
    {
        return 'someone.somewhere@clientwebsite.com';
    }
    public function acceptsHtmlEmail()
    {
        return true;
    }
}

class Employee implements Emailable
{
    public function getRecipientName()
    {
        return 'John Doe';
    }
    public function getEmailAddress()
    {
        return 'john.doe@ourcorporateemail.com';
    }
    public function acceptsHtmlEmail()
    {
        return false;
    }
}

Sample on GitHub

Implementing an interface: Simply means that we have defined an interface, and the class which implements that interface conforms to it. Then if we define Emailable as a type hint, PHP will force not only that the class implementing the interface, but also that any object parsed into an Emailable type hinted parameter conforms. Otherwise it’ll throw a hissy fit and not work

Scope!

The big one that catches a lot of new-to-OOP developers out is variable and method scope. So here is a quick and simple one:

  1. Public – these methods and properties can be accessed (as long as the object is instantiated) from anywhere that has access to the object
  2. Protected – these methods and properties can be accessed within this object (or derivatives)
  3. Private – These can only be accessed specifically within this class
  4. Static – These can be accessed from the class itself, without needing the instantiation of an object
  5. Constants – As in PHP itself, these never change

That’s the long and short of it. Word of warning! Always assume your code is going to be copied, recreated and used throughout a system and if it is open source by anyone anywhere in any way they feel like it. So be very careful what you expose as public, once it’s public you have to assume code is relying on it, and as such ensure you are backward compatible – what I’m saying is it is easier to change $myProperty and myMethod to be public later, if they were protected before, than to change them from public to protected – because who knows what you might break!

Accessing properties can be done as follows:

Please do not try to run this code, it won’t work 🙂

<?php

class Scope
{

    // I will never change
    const GITHUBURL = 'https://github.com/johnothecoder';

    // I can be called from the class, without instantiation, and can be shared across multiple instances
    public static $fullName = 'Matt Johnson';

    // I can be access from anywhere the object exists
    public $alias = 'JohnoTheCoder';

    // I can only be accessed from within Scope or a class which extends Scope
    protected $name = 'Matt Johnson';

    // I can be called from anywhere
    public function getAlias()
    {
        return $this->alias;
    }

    // I can be only be called within Scope (or classes which extend scope)
    protected function getName()
    {
        return $this->name;
    }

}

// Executing some code

echo Scope::GITHUBURL;
echo Scope::$fullName;

$scope = new Scope();
echo $scope->alias;
echo $scope->getAlias();

// But I can't do this
echo $scope->name;
// Or this
echo $scope->getName();

As always, sample available on GitHub

I can’t really talk you through the full spec of this one, as there’s not much to talk through, really it’s just a way of showing you what can and can’t be done within the scopes of an object.


Hopefully this article has been of some use to those of you looking to get into the big wide world of object orientated programming with PHP. Next time I will be covering how to use Dependency Injection, the Factory and Service locator pattern and polymorphism to your advantage 🙂

Thanks for reading!

Keep your eyes on the prize, money matters

In this article I am going to share with you some of my thoughts about the business aspect of web development, and how that needs to apply to our principles as web developers (or indeed contributors to any project).

As programmers, developers, coders, whatever you want to call us, we solve many problems. In essence our entire job is to help businesses solve problems, we do it with technology in the same way that accountants do it with financial matters. When there are no problems left to solve we try to make things better.

I believe that good web developers know a range of technologies and how to apply them, this may be in the form of technologies or languages, it may be in the form of methodologies or frameworks, or content management systems. I can’t make an educated decision on the nutritional value of a Wispa Duo (my favourite chocolate bar!) and an apple, if I didn’t know the apple existed, or that the Wispa is bad for my waistline. For the record I concede that I am festively plump in February, and that’s fine.

Now, in order to normalise the many ways of skinning a cat, and to create maintainable software – remembering that money is everything – we, developers, have created a bunch of rules. Things like the SOLID principles, MVC architecture, the separation between logic and display, and everything like that. Hell, WordPress is widely adopted because it solved a common problem with easy (blogs and brochure sites), without having to hire a web developer every time.

So we have all the rules and, unless we have a decent reason not to, we should follow them. Absolutely, without a doubt, not questioning it for a minute. Well, maybe a little bit. You need to know the rules exist, and how to apply them, and I’m a strong advocate of all of them in almost all scenarios.

But the reason I’m an advocate of all of these things has nothing to do with whether I like them or not. They do help us build better software, undoubtedly. However, that’s not the point. The point is fast to build, easy to maintain, quality software is good value for money.

The reason I’m an advocate of SOLID, of MVC, of the various issues of PSR and all of those things, is because it makes my life easier, but the more important side effect of this is that it means I can build and maintain software quickly, with high quality, and high maintainability. It means when the business wants to see my output, or modify a requirement, or change something I can do it. It makes me an asset to a business, rather than a burden, a “no” man or a “that’s going to take some time, boss” guy.

This is why I’m an advocate of rapid application development frameworks. Because they allow the rapid development of high quality software. Time is money, so as far as our value to a business goes it’s about producing high quality stuff and doing it quickly. The same goes when we have to maintain it, which is why the rules are good.

This in mind, I don’t mind bending the rules when there’s a decent case for doing it. If the code is clear in it’s function, it is easy to work with and easy to find. I don’t see the issue.

I could be wrong, but I’m yet to meet a Managing Director, Chief Executive Officer or an Accounting Director who cares about PSR-2, PSR-4, MVC, OOP, SOLID or any of the cool stuff we insist we must know. And that’s absolutely fine! It’s not in their remit to know about those things, they’re our job.

It’s our job, and our responsibility, to deliver quality and efficiency. Once we are a few years into our careers we are expensive resources, with decent salaries, expensive equipment and software, usually a fairly high turnaround (most developers move on within 6 – 24 months). So it’s important we hit the ground running, and prove our worth.

I like making my clients and employers happy, with my ability to turn quality products out in record time. It makes my job far safer than ivory towers in legacy code. I don’t mind bending or even breaking the odd rule to achieve this, if another developer can work on, and modify/extend, the software with ease, then I’m happy. The rules are only there to make our life easier, if I’m not making life harder than I personally think any argument against it is moot.

If I’m showing a fast return on investment to the business, and there’s no question whether I’m providing value for money without cutting the quality of my work, then there’s no question as to whether I should be doing it.

Remember guys; we want to build awesome software that changes the world. We want to build quality software that’s easy to maintain and upgrade; but I’m hired by businesses. If I’m not making the business money, or showing a valuable contribution in decent timeframes, I’m not likely to be around much longer. Eventually I’ll be replaced, or the role itself dissolved and the work outsourced to someone who is doing the above.

Time is money, and money is time. Quality is important, but time is equally important. You have to be able to justify the resource poured into you, and you have to justify it by proving your worth and having tangible output