Software Engineering, Design, and Requirements

[WarFox]

Introduction

On this forum (and discord), as now and as in the past, we have talked frequently about Computer Science topics. However, we never discuss software engineering. So here, I would like to make a little change to that by making a little article series covering the topic. For those who work in the industry may not get much out of this. This article is geared towards maybe a new comer to programming who have maybe just built some small programs in python. Someone who is not receiving formal education and might not run into this on their own, or perhaps a computer science student who has not taken any classes in software engineering. 

What is Software Engineering?

Software engineering is a field that essentially takes some computer science and adds some engineering into the mix. The term is joined by Admiral Grace Hopper, who wrote one of the first compilers. Most importantly, software engineering is about applying concepts in computer science to build software systems in an efficient way. So, one could say it is a process of building software. 

Now, I would like to make an distinction between the two in an educational setting. An education in computer science is going to put more of a focus on the theory. During a computer science education, topics such as artificial intelligence and compiler theory are going to be important parts of the program. An education in software engineering is going to give some computer science education, but combine it with an engineering approach in building systems. It is important to note that a lot of computer science programs will offer courses in software engineering. Essentially it comes down to where the focus of the program is.

To tackle the distinction in the work place, there is not a major one. Both educational paths can lead one to a job at google. The difference might be, a computer science student might walk out of school already know a bit about artificial intelligence. A software engineering student may have to walk out of school and to some self-driven learning. Which is okay, the biggest corner stone of an engineering degree is learning to learn in a fast and efficient manner. 

Why is design important?

Building small programs that do one or two tasks are simple. An example can be making script in python that automates a hand full of tasks or a basic FTP server. However, when making large systems, the game changes a lot. There is a difference in building a solitaire game in comparison to a point of sale system. There is also a higher degree of risks involved. A solitaire game that crashes or has bugs may not have any serve consequences except that the game ends. A point of sale system crashing can cause great harm to a business, leak information, etc. We mitigate this by having design and a process to go with it. Instead of planning and implementing a system in our heads, using tools to express the idea, communicate about it, and evaluate it. It also helps to maintain an already existing system. Maintaining a program that consists of 100 lines is easier to maintain without these tools than a program with 100000 lines of code and a few files.

Some things to keep in mind. The purpose of a design process and engineering in software is to eliminate complexity. The larger a program grows, the more complex it will become. We will not eliminate complexity, but we can reduce it. Reducing complexity also reduces the cognitive load on us as developer/programmers/engineers. Would it be easier for me to hand you the source to a software system and you read through it to understand what it is, what it does, and how it does what it does? Or would it be easier for me to give you design documents that give an higher level of abstraction of the parts and peices? If you think the former, perhaps during this series I can convince you otherwise.

Design is also important because it will give a quicker way to spot problems with a software system and potentially fix an issue earlier rather than later. There are really interesting statistics on this topic that are shocking. A good place to look for this is in the famous Uncle Bob's (Robert C Martin) books Code Complete and Clean Architecture. When working in the industry, a faulty implementation based on a poor (or no) design can easily start racking up into millions of dollars for a company to fix.

Really important to think about with the last paragraph, so much that I want it isolated is this, programs built around good design are easier to maintain. When making software, our standard of quality should not be "just good enough" or "it compiles." We should design while being forward thinking. Right now it compiles, but when you want to add a new feature, how hard is it going to be to implement? We can make programs modular and way easier to make changes to down the road by putting in time upfront with design. There are also suprising stats on how, one may think jumping to code is the fastest way to get done, but this is not really true. By investing time in design and actual engineering of a software system, you will tend to get to the final implementation sooner. A big reason is, having little to no design means that in the future, you will probably have more bugs and design flaws to work out in the testing stages of the software life cycle. By having design, you can code faster since you have something to code against, and you will eliminate time in the testing phase by having to go back and fix fewer design problems.

Prerequisite knowledge

There is some prereq knowledge that I will expect you to already have. If you do not, topics and ideas may be harder to grasp in future articles. I would advise for you to learn these topics to at least a novice level. They are:

1. OOP Programming language and concepts (I will be using Java as my reference)
2. Set theory
3. Some knowledge of UML (I will try to explain everything needed as best as possible, but a little extra knowledge other than just what I will be writing about would be a good thing).

Step One: Requirements

The first step in designing a software system is knowing what the requirements are. This can be an idea that a customer has for you of a software system they need. An example could be an inventory management system, a social network platform, a chat service, etc. Or the requirements can be an idea you have of a peice of software you want to develop as perhaps an open sourced project. If it is the former, a customer will probably give a document that described the system or tell you about it (take notes). If it is the later, pretend that you are writting it for a system you want someone else to build for you. 

For this article series, I will use as an example a point of sale system for a car dealership. Below is the requirements document.

Spoiler

The CarShopper Point of Sale app is an app that a car dealership is going to use to handle the purchases made by shoppers. The dealership has a location and a number of sales persons that are employeed. Salespersons are capable of querying the system for cars that are on the lot. They are also capable of adding new cars into inventory and deleting cars from inventory when they make a sale. Each customer will make an appointment on the phone that a customer service representative can schedule. Each appointment has a customer and a salesperon and date.

Each customer put into the system is a person who has atleast had an appointment. Their account will hold details such as address, email, and phone number. If they make a purchase of a car, their account will also hold financial details for the purchase. There will also be a running record of previous purchases since we give a discount to returning customers. 

The system has a list of cars. Each car had a upper and lower price range and a sticker price. Some cars are able to be customized, such as a different engine. 

Our dealership only carries 2 tyes of cars; a camary and a focus.

Using the requirement documents, we can extract information that will tell us key aspects of what the system needs. The first thing to do is look over the document. Next is to read the document over again and extract out noun and noun phrases. Here are some nouns and noun phrases that I extracted from my example document.

Appointment
Customer
Salesperson
CustomerServiceRep
Car
Engine
Dealership
Address
Focus
Camry

You may be able to spot some more, but this is just a short listing to give the idea.

From these nouns, these are going to represent classes we know our system will have. 

Next thing to do is analyze the document again, extracting verbs this time.

Customize
Purchase
Query Inventory

Feel free to look for more, these are just a few to give a general idea.

The verbs are doing to represent functionality we know our program will have to provide. The program must facilitate the customer making a purchase. The program must allow us to query the inventory of cars that are in stock. The customer will have the ability to customize a car by changing the engine.

Using the nouns and verbs, a high level abstraction starts to take place around what the system will look like.