What are the different types of requirements and why does it matter?


A software product is usually built with a purpose in mind. There is a reason a good number of web application domains end with “.io “. It literally means Input Output.

Your product takes in some raw information and returns more valuable processed information.

As usual, the devil is the details. What does raw information mean? What does output mean?

Scrum typically adopts user stories as its template for expressing its requirements.

This simple structure of:

    As a __
    I want to___
    So that __

Elegantly captures what the software should do and why.

Still, as the product gets bigger and the requirements pile on, I find it useful to impose some categories on the backlog.

In this entry, we will be looking at some categories which I have found to be useful.

User requirements

At iHub, we pride ourselves in our Human Centered Approach. The simple reason is it works.

The software serves people. At the end of the databases, activity streams, object storage etc is a person trying to get something done. Your success is measured by how successful this person is.

It then helps to acknowledge user requirements as a category on its own.

A typical requirement would be

    As a *researcher* I want to *have my results sorted by relevance* so that *I can get my work done faster*

Business requirements

We talk about the wonders of technology, from the aeroplane to the mini computer in our pockets. Yet, I would argue the biggest invention by humans was the enterprise.

Businesses, are the engines of our society, working behind the scenes, they provide us with all our material needs.

No matter how good, the software or how well it serves the users, if the business does not provide value to its owner then it’s as good as dead.

With this in mind, you must seek to also clarify why it is the client wants the software product built in the first place.

This is usually captured in the client’s vision statement. Of this, the software serves only a part of it.

An example of vision statement from Amnesty International

A world in which every person enjoys all of the human rights enshrined in the Universal Declaration of Human Rights and other international human rights instruments. 

If you happen to be contracted by Amnesty International, you need to remember to imbue this inspiring vision in every line of code you ship.

Non-functional requirements

Robert Gardy in his 1992 book Practical Software Metrics for Project Management and Process Improvement

Came up with the acronym FURPS+

This represents:

  • Functionality
  • Usability
  • Reliability
  • Performance
  • Supportability

The “+” in FURPS+ also helps us to remember concerns such as:

  • Design requirements
  • Implementation requirements
  • Interface requirements
  • Physical requirements

The idea is in addition to doing what it does, software is also required to do it well.

How effective do you think Google would be if it took 5 minutes to give you a response to your query?

I believe by categorising your backlogs in this way, you will able to get more ideas on what is to be included in the final product as well as appropriately prioritise the various backlogs resulting from it.

How do you categorise backlogs in your own organisation? How did you handle it? Talk to me in the comment section below or on my twitter @jchex


Sources of change in a software project


Change is an integral part of the software development process. It’s what makes software soft. In fact, change is so important in software that it get’s it’s very own line in the agile manifesto

    Responding to change over following a plan

It’s been a long time since software teams believed in the unchanging quality of requirements documents, but we are yet to fully understand where change comes from and how it affects us.

It costs far much more to make core changes during development than it does at requirements. Boehm and Papaccio estimate it at 50 – 100 times more. Even with the advent of agile techniques, it is still worth it to control change as much as possible.

In this entry we shall be exploring the various sources of changes, this should hopefully help you anticipate and identify impending changes as soon as possible.

Change from the customers

Of all the sources of change, this is the one worth most consideration. The reason is that as a consultancy or even engineering department, you want to harness change as a competitive tool for your client.

No matter how well you run your requirements gathering sessions, there are requirements you are bound to miss. This is because knowledge builds on knowledge ideas on ideas.

To illustrate this point, think of a car. The first car was a very basic box with wheels that happened to move. But from this idea, people began asking questions such as:

  • Why can’t the seats be more comfortable?
  • Why do I have to be hot in the car?
  • Why do I have to manually change gears?

Today, these previously extraneous features are deal breakers.

In the same way, once development has started, your customers are guaranteed to have new ideas as they see your progress.

In this kind of situation, you want to carefully weigh your options. You don’t want to do exactly what the customer wants you may end up always chasing after the new shiny thing. You also don’t want to completely ignore their wishes under the guise that you know best.

Change from sales and marketing

This part particularly affects product companies.

The product owner declares this Big Hairy Audacious Goal

    We will build a one stop best in class application within the next 6 months

This is a great goal and everyone is excited about it. The engineers get to work “banging” it out. Somewhere within the development window, the competitor does a release that you had not even thought about. The sales team also wants to be able to sell the new feature so they insist that is also put in the product after all our product is best in class right?

It is tempting to think of your application as a big checklist of features, this is dangerous because then you will be locked in competition with other firms to produce more and more.

Kelly Walters makes a compelling argument in Agile Principle 8: Enough Is Enough! that you likely don’t need to develop 80% of the features.

Perhaps then the product owner should have come up with a better goal say

    We will build a product in the next 6 months that will improve our customers margins by atleast 10%

Change from developers

Developers, my favourite group!

More than any other stakeholder, developers have the highest intellectual and emotional investment in the project. They are the ones who had to deal with the design flaws, unexplainable bugs and late night coding.

Yet to them, requirements are usually provided as a checklist. In this case am also looking at a list of user stories as a checklist. Without an organising theme, developers will do what they do best, write the best-designed code that they can conceive off.

The problem here is that the devil is in the details. Your DBA may end up writing code that shortens query time from 10ms to 1ms. This is great, except for the fact that no one really specified that they have that requirement. Another example would be where your front end engineer goes out of their way to guarantee that the settings page will work for all screen sizes.

I believe by actively watching out for this sources of change, you will be in a better position to manage them when the changes do come.

What are the sources of change in your own projects? Talk to me in the comment section below or on my twitter @ jchex


Hidden risks to project success


A story is told of a product manager who got a complaint from one of their major clients. The complaint was addressed to the apparent slowness of the app when getting data from the server. As it turns out, the PM knew a code ninja from back in the day. The PM had heard that the ninja has been working on a customized SQL engine that enhanced query performance on products such as his by a magnitude and in some cases even more.

So he had the ninja brought in to demo her invention. The new library proved true and the PM promptly had the developers implement the library on a hotfix that was then released to the major clients.

Once the new app got into production, it’s weaknesses started showing, for some reason the library was updating wrong records. The PMs company got sued, he tried to pass on the suit to the developer but the developer promptly pointed to the copyleft. The company ended up losing millions in the suit and even more from a tarnished reputation.

In today’s entry we will be looking at some basic guidelines to avoid such mistakes when making design decisions.

Fighting complexity with complexity

Software projects are incredibly complex creations. It is tempting to assume that the answer to creating this complex products lies in crafting complex designs. You would be wrong.

The practise of XP explicitly admonishes this belief in their credo.

    I have been surprised many times by how efficient a simple design can be. Simple designs often out perform highly complex yet theoretically optimized designs.

John Gall puts it even better.

    A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work. You have to start over with a working simple system.

Sometimes a monolithic app is the best answer. Your job as the developer is to deliver business value. Engineering skills are worthless if they can not generate economic value.

Simple designs require deep understanding of the problem you are trying to solve. This is hard work, but worth it.

No design

It is at times easy to confuse the concept of simple design with no design at all.

Doing a project with no design means you accrue a ton of technical debt in the process. As we have discussed in How you pay for technical debt when the debt falls due, your project will not stand.

Lower level languages

Very few developments in the field of software engineering have been able to provide a 10* gain in productivity.

F.Brooks famously stated:

    There is no single development in either technology or management technique which by itself promises even one order of magnitude of improvement within a decade in productivity, in reliability, In simplicity.

This statement was said in 1986. And it held true. But before then the said improvement was actually achieved when compilers were invented. Suddenly developers no longer had to care about machine code, only the business logic that they wrote.

From this era, the field has advanced greatly with successive languages abstracting the machine even more. Modern day languages have syntax that more closely resembles business parlance than scientific jargon.

Yet there are developers out there who want to take us back to the old days. Claims are made of the speed of lower level languages such as C or even worse assembler languages.

Unless you have a very strong case, avoid this languages and the developers who insist on using them like the plague.

Unfamiliar processes and tools

Developers are attracted to new shiny tools. That is a fact. Wether its a new IDE, language or even note taker. We love the novel.

Unfortunately all new tools have unknown kinks. It takes time for the product to mature. Obviously if you stuck to only the tools and processes that you are familiar with, you would become obsolete. With that said it is still better to err on the side of mature tools so that your team can focus on the product you are building rather than figuring out if whether the issue you are dealing with is a bug or a feature.

In my experience the above are the design problems that keep on creeping up. Tell me about your own experience on my twitter @jchex or on the comment section below.


How NOT to debug

They say patience is a virtue, if you are a developer you need saint like patience to handle the notorious case of the bug.

Ever since Grace Hopper coined the term debugging our applications have gotten much better at creating harder bugs to debug. At this age, a moth in your machine would probably not even register as a fuss worthy bug.

While there is no “right” way of finding bugs, there certainly is a “wrong” way. Today we are going to be looking at some of the most common.

Output statements

God bless Taylor Otwell for this little tidbit


The dd function dumps the variable passed on to it and then halts the script. By carefully using this function and some binary search chops, you can quickly identify problem areas in your code.

Most programming languages and frameworks provide this functionality in one form or another. Also it’s very easy to implement yourself.

Just like any other good thing, if it’s overused it becomes a problem. Just like any other good thing, its frequently overused!

It’s quite easy to tell yourself that I will put this code here to test if a bug is here and remove it later, but why test the memory gods?. Perhaps you will leave it nested in a conditional with a branch that is rarely executed. At least, rarely executed when you are testing your code. Guess when the branch will get run? Did you guess in production?

So what can you do about it?

Invest in a proper debugger. A tool like xdebug may take far longer to grok but once you master it, the rewards will be worth it.

Code like hell

This one is for all the Code Ninjas out there.

Fortunately I am not a ninja myself (See Why I am not a code Ninja). I am yet to change my sentiments on the matter.

The Code like hell style of development is where the code ninja pops up his/her favourite code editor and starts spitting out code. Damn the requirements and design.

Codebases that we’re coded in this way have a tendency to hide very hard to find bugs. The bugs are usually due to ninja level stupidity that mere mortals just can not comprehend.

If you find yourself debugging such an application, I am sorry my friend, the app is the bug.

So what can you do about it?

Follow a standard development methodology. Yes, even waterfall is better than code like hell. However if you are the unfortunate soul tasked with maintaining the application, start refactoring the code as soon as you can.

Versioning? For who? For what?

Git as defined by wikipedia.

Git is a widely used source code management system for software development. It is a distributed revision control system with an emphasis on speed,data integrity,and support for distributed, non-linear workflows.

Git as commonly used.

Git is a folder that can be pushed to a remote folder called github.

This mismatch in intend and use is characterized by thousand line codebase with one commit.

Unfortunately this scenario is all too common, even today. The effect of course is if you accidentally introduce a bug. You have no way of tracing it back to its point of origin.

So what can you do about it?

Learn to use version control properly. It really is not hard. In fact by simply using gitflow 90% of your problems would disappear into thin air.

Who cares about the need

Surprise surprise most applications we’re actually created to serve a need. Digging your grimy hands into the code’s innards without the slightest clue on why it works the way it does is simply disrespectful.

What you think is a bug just might be a feature.

    My software never has bugs. It just develops random features.

Ok that was just a joke, but seriously take the time to know the original intent.

So what can you do about it?

Take sometime to first check out the documentation and unit tests before starting the debugging. None of those exist? Refer back to the section on “Code like hell”.

Fix the symptom

With a few notable exceptions, a good number of clients just can’t explain their problem well. Instead they focus on what they can easily observe. As a developer you (hopefully) can see more. You see not just a misaligned form, but a missing tag. So what is a busy developer to do? Hard code the position and fix the immediate problem or rework the entire page to bring in all missing elements?

In the first scenario, the developer has just chased away the bug, be sure it will be coming back with its brothers, sisters and beer buddies. In the second scenario the developer solved the problem that caused the bug, not just the symptom of the bug.

If it took you more than a second to figure out the right choice you may want to check out How you pay for technical debt

So what can you do about it?

Don’t settle for the obvious, dig deeper. Try to find out what is the true cause of the issue you are now experiencing. The client will be happier and you will gain insights that will help you through your entire career in software.

How do you debug in your organization? Tell us in the comment section below.


One design to rule them all


This post is a continuation of Metrics on quality of software

As developers we like our solutions cut and dried. For every problem there is a tempting desire to believe that there exists one perfect solution if only we look hard enough.

Yet we have already talked about the futility of such a belief. The tl;dr version is that you only fully understand your project once the code committed, not a moment before.

This may not be a problem if a single optimal design existed, but the reality is that the design space is exceedingly rich. Wether you chose to believe it or not, there is almost certainly a better design than what you just committed.

With this in mind then the goal is not to find an optimal solution but to evaluate trade offs for what best serves your purpose. To that end I present a Metrics on quality of design.


All good things come from the heart, and as we all know managing complexity is at The heart of software engineering

From the lofty heights of this generalities you may be wondering how do you measure complexity in software. Well there are a myriad of standard software metrics but almost all of them require the project to be done before you can apply them. I think the most intuitive is to simply ask yourself.

    Does this design allow the developer to concentrate only on this part without knowing any other part of the project?

Make a habit of asking yourself this question regularly as you are spitting out the code.


You can talk about speed or maybe even Big Omega but as far as I know, none of this ideas owns a shotgun. Do you know who owns a shotgun? The developer who is going to maintain your code, and yes they know where you live!

In your design always assume that the next developer to touch the code lacks any contextual knowledge. As such the design should be well documented and even better, be rich in the quality of affordance.

As a rule of thumb remember

    It is easier to make changes in your code during development than it is during maintainance.


Software reuse is a very old and a very successful idea.

We routinely reuse various software components in writing our code, math function, string manipulations etc.

Yet it’s a rare breed that writes their own software in a way that can be reused! Be the change we all want to see.

Dependency management

Remember back when we talked about trade offs? Well here we have one in practise. To reuse code means to increase the dependency between your code and the code you are reusing. Yet this is a necessary part of advancing your software.

    When we don't control the dependencies in our code, the second law of thermodynamics comes into effect in its full glory. 

As with all necessary evils, we need to keep dependencies to a minimum and for large projects, a clear interface should be defined and the dependency fulfilled at compilation.

Check this awesome article by Martin Fowler for more context InversionOfControl


Have you ever made a change to the mapping area of your application and have the login area explode? This has happened to one of my colleagues and needless to say, the entire code base had to be scrapped!

Changes to your code need not be catastrophic, in fact with a little forethought your design should be able to handle such changes gracefully.

    Welcome changing requirements, even late in development. Agile processes harness change for the customer's competitive advantage.
    ~Agile manifesto

To do this make sure areas most likely to change are properly insulated and interfaces defined.

Essential ism

    The wisdom of life consists in the elimination of non-essentials
    ~Lin Yutang

Mr Lin would have made for an excellent developer!

Most code written is simply fluff, this wouldn’t be a problem except for the fact that the extra code adds very little value yet manifests its full weight in maintenance costs. The single most effective way of dealing with it is to cut it out.


Whenever standardization is mentioned, developers get belligerent perhaps under the assumption that they are being treated as interchangeable cogs.

But the truth is, standards confer leverage, by using standard tools and practises to mill through the mundane bits, you free up the energy to exercise creativity on what is truly important in your project.

Have you come across a good design lately? Do you feel that the developer took into consideration the principles mentioned above? Tell us what you think in the comment section below.


Objects can do more than bark

When we talk about OOP and classes to most fresh developers the first thing that comes to mind is a dog. This is because years of training has tought us that a class is a representation of an object, an object with behavior and state. Such as a dog, a dog that barks.

You maybe thinking that this kind of zoological analogies for engineering principles is too simplistic, and you would be right!

While classes in programming can be used to model real life objects this is not what they we’re designed for, in fact this use happens only in fringe cases!

So then what are classes to be used for?

To find the answer to that we must dig way down to The heart of software engineering.

Did you guess it? Yes classes we’re built with the explicit mission to manage complexity!. Incredible isn’t it? Maybe not so much, lets look at some ways in which classes are used in practise.


As good engineers we know that our code is likely to change especially for tricky areas. In such cases it makes sense to write a class that exposes an interface that is much easier to understand in context and forget about the details pertaining to implementation.

Examples of details to hide include:

  • Complex algorithms
  • Database access routines
  • Business logic

Reduce complexity

For especially complex routines, it makes sense to break them apart into simpler routines and then package all of them into the same class. That way it’s easier to understand each of the individual components of the algorithm in isolation.

Global data

Global data is evil! While most languages have made advances in preventing use of it, for obdurate developers there is always a way. For this cases, classes can provide a way to package all data needed globally into a single class and then use an existing pattern, say Singleton to access it.

NB: Singleton is considered by some to be an anti-pattern. Hector Matos gives a more extensive treatment on the subject here http://krakendev.io/blog/antipatterns-singletons

Packaging relating functionality

Most languages provide a standard package for mathematical and statistical functions. You may however have certain special needs for your own software in which case you can package the functions in one class.

Some examples would include:

  • Rate calculations
  • Financial functions
  • Engineering functions


Classes are especially suited for control of knowledge in your application. Building a class to say control access to outside services or provide meta data greatly simplifies design.

You may want to build a class that say:

  • Validates information
  • Controls external devices

In the above mentioned cases, thinking of classes in the primitive real world object sense is not only useless it can actually be harmful.

How do you use comments in your own design? Tell us in the comment section below.


Dealing with elusive bugs

We all have been there before, you make an update to the code, hit refresh and get the dreaded Error Exception. No error message. No way to track what you did wrong.

The sensations that follow can only be described as horrid as you scramble to sort the issue yet you still end up in the same place. Stuck. At this point you start doubting why you even joined this horrid field, with its horrid deadlines. Maybe, just maybe you really are not cut out to be a Software Engineer.

Well the good news is that you are not alone, in fact I am going to discuss how I deal with this very issue myself. The bad news is there is no magic bullet. With that said lets start exploring, but first a story.

In southern Mynammar, locals still hunt monkeys for food. Now if you have ever dealt with monkeys you understand this animals are rather intelligent beings. Yet the burmese invented a very simple trap to catch them.

The design of the trap consists of a hollowed out coconut tied down. The coconut has a small hole through which a monkey can squeeze its hands in. Rice, a delicacy to the monkeys, is put inside the coconut.

The monkey slides in its hand through the small hole and takes in its fill, however it now can not remove the hand.

The hunter then is at leisure to come in and take his game.

Back to our stuckness. We tend to be a bit like the monkey. In solving our problem, we hang on to an idea of the solution. Enticed by it, we don’t let it go even when we feel intuitively know nothing is coming of it. We tug and tug. But what if you we’re to advice the monkey, would you tell it to continue to tug?

Getting unstuck

  • Retrace where you have been. How did you come up with this solution? What informed the decision
  • Write the reasons down. And I mean physically, not in your head!
  • Stare at your list
  • Take a break. Minimum 30 mins. Ideally a nap would be even better.
  • Come back and start writing other possible solutions
  • Start with the first idea, i.e the one that got you stuck
  • Write all the other ideas as they flow. This is not the time to judge write whatever comes to mind no matter how stupid

While not a guarantee, its likely that another potential solution will come to you, this one more suited to your problem.

Have you been in such a situation before? How did you handle it? Talk to us in the comment section below.


Ways you are breaking encapsulation without knowing it

I have seen good developers, nay great developers break encapsulation and even more interestingly, they didn’t even know they we’re doing it! How is this even possible? On this piece we shall explore this phenomena.

First, lets look at what encapsulation is. Encapsulation is one of the four pillars of Object Oriented Programming commonly abbreviated as OOP. The others include inheritance, polymorphism and abstraction. The principle behind encapsulation is hiding of data and behavior of an object to prevent it from external corruption and reduce overall complexity.

In practice this is implemented in most OOP languages by use of certain keywords such as:

    - protected
    - private
    - public

The language specific implementation shall be left as an exercise to the reader. Please check your language documentation.

Today however we shall be looking at a particularly insidious way of breaking encapsulation that is exceedingly difficult to diagnose and correct . Today we look into the world of semantic encapsulation

Semantic encapsulation is broken when we depend not on the public interface offered by the object but on some prior knowledge of the implementation.

This concept is rather hard to grok, as such will give some few examples.


class A
        function initialize()
                //Do some bootstrap work here
        function performFirstOperation()
                //Now do other operations


In normal use of this code we would simply call $a->performFirstOperation() safe in the knowledge that the requisite initialize() operation will be called.

Do you see the gotcha there?

To protect ourselves we would need to change the method type to either protected or private that would then ensure initialize can only be called from outside the function.

Lets look at another example


class User
        function retreiveById(Database $database)
                return $database.runSql("select * from users where id=1");


class Database
        function connect()
                //Connection logic
        function isConnected()
                //run logic to check connection status
                return $status;
        function runSql($sql){
                //runs the sql query


What about that one? Did you see anything of interest?

Well in this case the User class is very intimate with the Database class, knowing not just how to connect to the external service but also how to check if its connected to start with!

Now for our final example.


class A 
        static $b;
        function __construct()
                $b= new B();
                $b->interesting_fact="Some interesting fact";


class B
        public $interesting_fact;

//Earlier in code

$a= new A();

//later in different part of codebase

$bInitialized= A::$b;

In this case we initialize a Class B from Class A where we modify its behaviour or data in some way that is useful to our business rules. However since we already know that the Class B is already initialized we can now use it later on in our code safe in the knowledge that the class has the right data.

This again is a demonstration of how prior knowledge of implementation is used to break encapsulation.

I believe third time’s the charm and we now have an even better understanding of encapsulation.

Have you encountered the issues highlighted above in your code base? Talk to us in the comment section below.


Isolating Change In Software Projects

Software more than any other human creation has had the largest impact in human society in a very short period of time.

It’s strength lies in its softness that is the ability to adapt, reuse and even re purpose existing software to build better and better products for cheap. But hidden in this strength is a weakness, change very quickly degrades systems to a mess no one can understand. As we have already discussed before in The heart of software engineering this kind of complexity is the death knell of the project.

Our best defense against this particular blow is to actively manage the areas which our software is likely to change. As such I have prepared a tickler list of such areas as I have experienced in my own practise.


From File based to relational to object oriented to NoSQL, the world of persistence has changed a lot in the last 15 years. If your codebase was tightly coupled to any one of this paradigms, at best the product may not be taking advantage of advances in the field at worst it may have already been wiped out! Yet the effects are not always so grandiose, sometimes you may realize that another database in the same paradigm may serve you better, say Postgres over MySQL for GIS data.

For this reason it makes sense to decouple your code from your DB. This is usually the easiest to do because any good ORM would do the trick.


Better hardware comes out every year, I am not talking about just Moore’s law but rather entirely new hardware or new specifications for existing hardware.

You should wrap all code that interacts with the hardware in a class or module then access that via a standard interface. That way you can easily switch out implementations as need be.

Business rules

Business that thrive have learned the value of evolving to adapt to the current trends in its industry. The product owner will expect the codebase to evolve to meet the changing business model.

The topic of adapting your code is covered well by Eric Evans in his book Domain Driven Design. This is a must read for anyone engaging in the business of software consulting.

However we can still take care of the basics including things like

  • Giving meaningful names to entities in your application
  • Encapsulating business rules in classes
  • Accessing constants such as tax rate from environment variables

Framework dependency

It’s considered heresy to write code without using a framework. Countless flame wars have been waged on the topic yet what the commandos in this war fail to see is that a framework is just a set of libraries meant to support your code. You should wrap any exotic functionality provided by the framework in packages or at very least define interfaces which then the framework would support. Otherwise when a better framework comes along the cost of the transition maybe prohibitive and your project will thus be married to its original framework.

Have you identified other areas in your code that seem to change frequently? Talk to us in the comment section below.


All about imports

Have you ever used packagist? What about PyPi? If you are like most developers, well at least the sane ones, the answer is a resounding yes!

What however may not be as unified in response is how to actually arrange the imports.

Thankfully a best practise exists. Here we go.

Top level

First things first, here you should import any standard library import. That is packages that ship with your language of choice.

from math import sqrt
from os.path import abspath

Mid level

Right below you should import any third party libraries you use. This include any libraries that ship with your framework.

use App\Http\Controllers\Controller;

Lowest level

This is where you put in any code that you are reusing from within the app.

import payroll.Employee;

That is as a general heuristic import first items nearer to the core language.

How do you import in your own application? Talk to us in the comment section below.