The problem

A lot of software engineers get into the industry and often end up starting to write code soon after they read the requirements specification. Sounds familiar? You might have done it too. Hard to admit? Can be. We are humans, after all.

Jumping right into the coding process might be a great idea for a simple coding challenge, where the objective is to solve a problem in as little time as possible, with potentially very few lines of code. You just have that very specific goal. You don’t have worry about future enhancements for that solution, nor do you have to think about maintainability of that solution. Once solved, the code might have to run through a set of tests and pass the criteria of the question. Fantastic! And you might even get selected for the next round of interviews! Great! So why think about design when you start working on a real solution?

I am glad you asked. If you read the earlier paragraph, you might have noticed already why design might be important. But most likely, you might have ignored it.

Software design is the process of creating a blueprint, most often as a combination of diagrams and documents, that adheres to the constraints of the problem-sphere, which can be used to develop code that solves the problem stated in the requirements specification or statement.

Now that is a definition in my words, so don’t expect to find that in a book. Because I haven’t written one yet.

But does that statement make sense?

What does it involve?

Creating a blueprint from the requirement specification is the key. That is not a simple process because the requirements are never a complete instruction set to code for. Now you might wonder, why? Why isn’t the specification a well defined document? If you gave it some thought, you would answer it yourself.

Requirements are most often, words, spoken by non-technical human beings, who have a problem that desperately needs a solution, which may or may not be to improve efficiency, either in life or at work. They know exactly, what they want and it is all in their head. But it is extremely hard for such a person to put this need into words in a form that can be devised into software. They know the constraints in their head, but most often, they fail to list all of it, or even one of it.

How do we help solve this?

How does one describe something that they do regularly to someone who has never done anything like it before or has no knowledge of that domain?

Did that question confuse you?

To get a feel for that, try to think of way to explain what, you, as a software engineer, do on a daily basis at work, to your grandparents or great grandparents, who have barely any knowledge of technology, programming, or even computers. This experience is exactly the same for your client. It is difficult and painful. You often have to take a step back, think hard and write and re-write. If users had the time for all that, they might have developed the solutions themselves. This is why software engineers need to learn to empathise with people of all spectrums.

Now, compare that to the problem specification for coding interviews. They seem to be well defined. Some even give you example inputs and outputs and even constraints listed out in mathematical formulas! Wow! What a contrast! They just speak the same language as you! Why do you think that is? Because, they are written by other software engineers!

Software Design in a diagrammatic representation often helps bridge the gaps in the requirement specification.

What or whom do I blame?

In the real world, as I described earlier, requirements come with a lot of gaps, leaving the coders with plenty of questions. You could, as an eager beaver, go ahead and start writing code for the requirement, based on a hell of a lot of assumptions that you make based on how to get the development done easily and quickly, so that you can mark that task as done. But that will lead to buggy software or something that doesn’t really meet the requirements of the user. However, you might finish your task, or think you finished your task sooner than anyone ever imagined. Only to get a lot more work later, as user or quality assurance feedback.

Most often, impatient software engineers, just blame the requirement specification for the buggy software. I have heard this time and time again, “why is that not in the spec?”, “we can only develop against a specification.”, “Why are the Business Analysts not doing their jobs?”. Sounds familiar? But are these questions pointing to a solution though? Not really. They are just what humans do best. Blame.

The job role, Business Analyst, was born as a result of this. Someone who could read/receive client requirements and magically transform them into a more detailed, constrained set of instructions that programmers can easily understand. But even a Business Analyst have limitations. They may not be from a software engineering background. And they might understand tech from a very high level. So what you get from them, would be something better than what the user would have given directly to you.

So from this requirement, whoever compiles it, it is the responsibility of the team working on the solution to read problem statement, and try to understand it, by asking as many open ended questions as possible to the source of your requirements.

This will magically help you get a deeper understanding of the problem domain. You might even end up saying, “Oh! I didn’t realise it was that complicated!”.

Some tools to create blueprints

Now that you have understood the the problem better, visualise it by drawing it. Create diagrams of any form. You don’t have to do a UML 101 to draw software diagrams. #

Start from C4 diagrams. Draw some boxes of the different components/systems that interact with one another. Try to visualise the journey of the item involved in the workflow of your client. Map out the constraints, identify external inputs that can have an impact on the workflow. And summarise your understanding with the user and exchange thoughts, you’ll be surprised how much clearer the specification is now. In the process, you have created a blue-print that any engineer who might come after you to refer and learn about the domain too! Isn’t that great?!

This why it is important to take a step back from the problem statement and think about the solution, instead of starting write code straight away. That will help you build the right software, in the right way.