2.2 Requirements and specifications


The development of a software product begins with a requirement for a certain kind of program and a brief specification for what such a program might be. The requirement is a little like a question and the specification is like an answer. Put a little differently, the requirement is like a request and the specification is a proposed solution.

The usage of the words 'requirement' and 'specification' is somewhat fluid, and you will find different conventions in different books on software engineering. In Software Engineering and Computer Games, we treat the requirement as a request for a certain kind of software and a specification as a proposed description of the software. And we stress that there is considerable interplay between the requirement and the specification. During this requirements gathering process, the stakeholders in the project try to converge on coming up with a requirement and a specification that match each other. The stakeholders might include corporate customers, investors, the managers, the programmers and perhaps a sampling of eventual users.

So, once again, a software requirement says what the target program is supposed to do. A requirement might be something as clear-cut as, 'Write a program which displays our inventory data in an attractive format,' or something less precise like, 'Write a Web browser that runs on cell phones,' or something open-ended like, 'Write a really nice game.' At the preliminary level, the initial requirement can also be called a vision or a software concept.

As well as saying what the program is supposed to do, a requirement may list some specific features that the program is expected to have. Sometimes a software requirement starts out very detailed, but more often it will be brief.

In industry, another aspect of a software requirement is that it will include some ideas about the marketability of the intended product. An industrial software requirement will say why the program is worth doing and why people will want to have it. Managerial types have a very persistent way of asking, 'What is the intended market?' So usually a software requirement will address this question as well as the question of what the program will do.

UML diagrams

In recent years there's been a movement to consolidate the different kinds of ways that software engineers talk about what they do. The result is a loosely defined set of names and conventions called the Unified Modeling Language, or UML. UML is primarily used as a methodology for drawing diagrams relating to the creating of programs. The fact that it is 'unified' means that UML includes the contributions of many different computer scientists, to the point where it is a bit of a catch-all. There are at least nine different kinds of UML diagram: use case, class, object, activity, statechart, sequence, collaboration, component, and deployment. We should also mention that much, though not all, of the UML assumes that you are using an object-oriented style of software engineering like we'll be discussing in this book.

In Software Engineering and Computer Games we'll discuss only these five kinds of UML diagrams.

  • Use case diagrams for software requirements.

  • Component diagrams for the dependencies of the source-code files.

  • Activity diagrams for program execution flowcharts.

  • Class diagrams for the high-level structure.

  • Sequence diagrams for interactions of program objects.

A basic thing to remember about UML diagrams is that they're meant to be quite simple. The primary purpose of UML diagrams is to make it easy for a project's various stakeholders to communicate with each other about the project. Keep in mind that a number of the stakeholders are likely to be non-technical. There's nothing like putting some UML diagrams on a white-board to get a discussion going. UML use case diagrams are of particular value during requirements gathering.

Another purpose of UML diagrams is for what is called forward engineering, where we move from a concept towards actual code. UML class diagrams are particularly useful when you are in the stage of working out the high-level design for your program. The UML activity diagrams are useful for understanding the overall program flow. And the UML sequence diagrams are good for working out the details of how your objects interact.

A third purpose of UML diagrams is for reverse engineering, that is, for understanding how an existing program works. This is in fact the situation that the readers of Software Engineering and Computer Games are in. In order to use the Pop Framework to build a new game, you need to have some understanding of the Pop program's design structure and running behavior. This is also the situation that you're usually in when you start working for a big company. They have some large body of code in place, and you're supposed to start maintaining or extending it. UML diagrams are a perfect tool for getting started with the process.

A use case diagram can help you understand what the program is supposed to do. A component diagram lays out the interdependencies of the source-code files. An activity diagram shows the overall program flow. Class diagrams show you the interrelationships between the kinds of objects the program uses. And sequence diagrams can clarify the details of how the objects interact.

Use case diagrams

In a UML use case diagram, you represent your program as a big rectangle. Outside the program you put one or more stick-figures corresponding to the actors, that is, the people or other programs who might make requests to your program. Inside the program box you put ovals corresponding to use cases, which are things the actors might ask the program to do. You may also draw relationship lines from actors to use cases to indicate which kinds of actors get involved with which kinds of use case.

Even more than other UML diagrams, use case diagrams are exceedingly simple. The stick-figures are a low-tech bit of psychology to make you to feel more engaged with what is really little more than a list of requirements.

A use case diagram for the Pop Framework code might look like Figure 2.2.

Figure 2.2. A use case diagram for the Pop Framework


Since Pop is both a program and a framework, its use case diagram mentions two kinds of actors: the users who play the Pop games and the programmers who use the Pop Framework to build new games.

Rather than going into a high level of detail about how we will display our graphics, we simply have the 'watch' use case to express the idea that the game should be pleasant to look at. The 'resize' case expresses the requirement that the game should be resolution independent. The 'adjust' use case expresses the fact that we require an ability to be able to do things like selecting game levels or resetting the game. The 'check progress' use case leads to a requirement that the game should display the current score, player health, and so on.

On the programmer side of things, we mention an 'extend' use case and a 'test' use case. Requirements coming out of the 'extend' case are that the code should have clear, easily extended classes, and that the various numerical parameters should be easy to find and easy to change. Requirements arising from the 'test' use case might be that the framework should have methods for randomizing parameters for so-called black-box testing, as well as an autorun mode in which the game 'plays by itself'.

Requirements gathering

A software requirement is a more or less detailed request for a certain kind of program. A requirement asks, 'Will you write a program to do such and such which appeals to so and so and runs on the following platforms?'

A software specification is a more or less detailed description of a program. A specification arises as an answer to the question posed by a requirement. A specification answers a requirement by saying, 'I can write a program with the following features, and its appearance and behavior will be something like this.'

As mentioned before, the key thing to realize is that ? like so many aspects of software engineering ? arriving at a final requirement and specification is an iterative process. This is the process we call requirements gathering.

It is essential to spend a good amount of time on requirements gathering before writing a single line of code!

Without enough requirements gathering you run the risk of spending a lot of energy writing a program that your customer doesn't want.

In order to discuss requirements gathering a bit more, let's think of a simple situation where you are the lead software engineer planning to create a program for some customer. The customer proposes a requirement, you propose a specification and show it to the customer, the customer alters the requirement, you alter the specification, and the process is continued until the customer has figured out what he or she really wants, and you have figured out an answer which the customer finds satisfactory. This is an example of requirements gathering.

What about the situation where you are developing a program on speculation, without any investors or corporate clients involved? Well, you really shouldn't try to develop a program for an imaginary customer that exists only in your head. You need to get out and talk to real people, to people other than yourself. If you're developing for the mass market, your 'customer' might be possible users. If you're well-funded, you might have a formal focus-group of users. If you're upgrading an existing product, your users might be your customer base. If you're pretty much on your own, your sample users might be whatever friends or family you can find who are interested in what you're doing.

In most situations there are project stakeholders other than customers. If you're starting a company, one of your stakeholders might be a venture capitalist. If you're an executive of a company, a key stakeholder might be an executive at another company that's contracting for you to write a specific program. If you're a low-level employee at a company, your most important stakeholder is your boss. If you're a student in a software projects class, your stakeholders are your professor, the other members of your team, and any sample users you can manage to talk to.

In each case one of the stakeholders proposes some more or less vague requirements and it's up to you to come up with a specification of a program such that (a) all the stakeholders agree that the specification satisfies the requirement and (b) you feel you can complete the program given the existing time, cost, and quality constraints.

Condition (b) means that in the requirements gathering phase you need to keep the Constraint Triangle well in mind. It's a mistake to 'gold-plate' the requirement and insist that you will be able to include a huge list of fancy features. Always remember the Constraint Triangle of cost, time, and quality. If there are some absolutely necessary fancy features which are bulking up the quality corner, you need to make sure you get allowances to the cost and/or time corners to compensate. If your customer, or your boss, or your marketing department, won't accept a realistic feature set, you should quietly start looking for a new customer or a new job. It's too stressful to work on a project that's doomed from the outset by unrealistic estimates.

The specification sketch

It's a bad idea to code without having any written plan at all. If you have a written plan, looking at it can keep you from going off on tangents that may not be crucial. And a short written plan makes a good starting point for discussions with others. So you really do need to write up a specification before starting to code.

What should a specification look like? We distinguish between two kinds of specifications: a short, casual one called a specification sketch, and a longer, cleaner, more formal one called a full specification.

An ideal full specification might consist of your class header files and a complete User's Guide for the program. Realistically, you usually aren't in a position to correctly write a full specification until your program's nearly done! That's why, to start with, we settle for a specification sketch. Better a sketch than nothing.

It's liberating to accept that it's unreasonable to want to write out a full specification before you write a line of code. In the real world, it helps to play with some code while you're thinking and to try a few things out so that you have some idea of what your possibilities are.

This is where the notion of a specification sketch comes in. If you feel like the only possible specification you can write up is a full specification, you're going to be tempted to not make any kind of specification at all and just start right in on coding. But if all you have to write up is a one or two page specification sketch, the process feels more like a helper than like an obstacle.

As your program evolves, your specification will gain more and more detail. Some aspects of the specification may not be worked out until you've written several builds of the code.

The specification sketch should describe four basic areas: (S1) the concept, (S2) the appearance, (S3) the controls and (S4) the behavior of the program.

  • (S1) Concept. The concept states what the program is about, and describes the unifying theme of the program.

  • (S2) Appearance. The appearance should be specified by a few drawings of what you expect the screens of your program to look like. For a very large project you might go so far as to make software mockups of sample screens, creating these either as paint program bitmaps or as outputs of a quick and dirty prototype program. But for a small project, a pencil drawing on a piece of paper may be enough.

  • (S3) Controls. The controls should be specified by saying how the keyboard, mouse, and more important menu controls will work.

  • (S4) Behavior. The description of the behavior should mention the main features of the program. It's often useful to step through how the program would respond to user actions in a typical use case scenario. Also describe how a typical user will get started with the program, and mention some expected tips for successfully using the program.

Suppose that your requirement is to write a computer game. A proposed specification sketch might be based on, for instance, the concept for a game resembling the PacMan game. (S1) The sketch's concept would also need to include an idea for a coherent graphical theme distinct from the graphics of PacMan. (S2) The sketch would include a drawing of the screen of your game. (S3) The controls are simply the arrow keys. (S4) Regarding the behavior, the sketch would have some details about how many enemies there will be, what the score for eating a power pellet will be, what the shape of the maze will be, and how the successive levels of the game might differ.

Of course the customer's response to such a specification might be, 'I want a new kind of computer game, not a clone of an existing game.' And then you'd need to find a way to make your PacMan specification more original, and continue on through the next cycle of requirements gathering.

    Part I: Software Engineering and Computer Games
    Part II: Software Engineering and Computer Games Reference