Requirements

Prelude to Object-Oriented Design

We expect you have some OOD experience already. If you feel you may be weak, read the following in e.g. the course OOD textbook.

  • Encapsulation of logical parts (Ch1)
  • Delegation and the power of loose coupling (Ch 4)
  • UML class diagrams (spread throughout the book; also see the OOSE UML lecture notes page for some links to other UML resources)
  • Basic OO design principles (Ch 5)

Phases of Engineering Design

There is a standard design methodology whenever you want to build buildings, devices, etc.

  1. Get the requirements the e.g. bridge is supposed to meet
  2. Make a complete design (blueprints, materials, building method, etc)
  3. Build (implement) it
  4. Test it to make sure its going to work.
This is called the waterfall model of software engineering.

Phases of Modern Software Engineering

Modern software engineering is a far more flexible variation on the above due to zero materials cost
  • Start with a first pass at requirements and design which will not be complete.
  • Implement the most-key features and get basic functionality running
  • As an initial implementation takes shape, use it to refine the requirements and design
  • Implement more features, continue to refine requirements/design more, and provide continual releases of the running application.

Schools of Software Development

  • There are many schools of thought on the best way to develop software as a team
  • We are not going to explicitly mention any of the schools here but you are encouraged to read up on them.
  • We are following some hybrid of the Agile, Extreme Programming (XP), and Scrum schools.

Requirements gathering aka Product Discovery

Step one in building software: understand what the goal is. This phase is also called Product Discovery.

  • Software projects involving n people start out with n very different impressions on how the app should be structured.
  • Your primary goal is to flesh out and unify those n visions into one
  • Extensive disussing, questioning, sketching is needed.
  • All parties involved need to be at the table: management, developers, customers.
Here are some useful "goal" documents -- if you can make these documents sing you have a unified vision!
  1. a Vision statement - a paragraph or two on the shared vision of customer and developers on what the app should do.
  2. a feature list - yes, a bulleted list of features the application should have
  3. Sketches/storyboards of user interfaces and how they are used
  4. Possibly some use cases - step-by-step sequences of how a particular scenario of user-app interaction should play out
  5. Possibly some prototypes
Other goals
  • Identify the potential different parties (actors) that will be interacting with the system, and focus on their needs when gathering requirements
  • Domain modeling: get a better understanding the underlying domain of the application (e.g. music file formats and copyright rules for a music streaming app)
  • Explore different frameworks and libraries that could be used, and settle on an initial plan.
There are also bigger picture topics to keep in mind
  • What is the market for the app? Who will actually use it?
  • What is the feasibility of coding it in the available timeframe? Can it logically be split amongst the team?
  • Look at the competition: do similar apps exist?
  • What is the team organizational structure? Strong leader, collection or leaders, or highly democratic?

Feature lists

  • List features the app should have, e.g. "Support Facebook login", etc
  • core features are the most basic ones, and extended features are long-range goals
  • We will look at some feature list examples in lecture

Use-cases

(See Chapters 2-3 of the HFOOA&D book)

Use-cases (also called stories) are sequences of events that represent behaviors the functioning system should have.

Use-cases are helpful in fleshing out an application:

  • The process of writing use-cases will expose details of expected functionality;
  • You can incrementally elaborate and expand on (or, shrink and remove) use-cases until they are stable and sensible enough to implement.
  • You can use the use-cases to help get started with coding.

Examples of use-cases

Chapters 2-4 and 10 of HFOOA&D are filled with examples of use-cases and their refinement.
  • One of the most complete examples is in the book on p. 124
  • We will review use-cases in a previous OOSE project.

Finding the right use cases

  • Use the feature lists, GUI sketches, etc as fodder for rooting out the use-cases.
    (HFOOA&D p. 78 and pp 304-305 give examples of extracting use-cases from feature lists)
  • Focus on the meaty cases with a non-trivial number of steps, the short ones don't need writing out.
  • Similarly, if a UI sketch or storyboard clearly shows the sequence of events, there is no need to duplicate that in a use-case.

Features vs use-cases

Features are single-sentence descriptions of features; use-cases are step-by-step descriptions of behavior. Here is a definition-by-example:
  • A feature of a library book checkout application could be simply "The ability to charge late fees for overdue books".
  • A use-case of the same application could be "return book and calculate late fee", a step-by-step scenario of how a patron returns a physical book, the book would be scanned, it would be marked as back on the stacks in the database, and a late fee if any would be computed and added to the patron's account.

The Format for Writing Use Cases

To standardize projects we will ask that you follow the enumerated list format on p. 560 of the textbook; the above-mentioned p. 124 example also uses that format.

  • Always include a Title which is a capsule summary
  • The body is the main path of the use-case, a numbered list of actions described in English
  • Alternate Paths of the use-case as per p. 124: other ways the use case could proceed
    (from p.124, take either 2. then 3., or take 2.1 then 3.1).
  • Optional Path -- some steps that could be skipped (steps 6.1-6.5 in the p. 124 example)
  • Make sure the use case starts with what initiates it (see "External initiator" on p. 75 of the book)
  • Use the step numbering scheme in the book, described reasonably well on p. 122.
  • You don't need to use alternate or optional paths, its a stylistic choice
p. 562 of the text presents other items you may find useful to optionally include.

Initial Architecture Proposal

See the HFOOA&D book pp. 310-... and 501-...
  • This is an initial proposal for the software architectures, frameworks, etc and how they will be deployed
  • You will independently need to evaluate different frameworks etc for your projects, consulting with us.

Domain Analysis

(See HFOOA&D book pp. 307-308)

You need to thoroughly understand the domain of your app before you can even begin to design it.

  • Domain Analysis is any activity which increases the understanding of the underlying domain the software is working in.
  • Example domains that need analyzing in detail:
    • In a restaurant (even without a computer) the "domain" is the actual restaurant with entities including Orders, Menu Items, Tables, Payments, Receipts, Waitron, etc.
    • In any implementation of a board/card/etc game there are the detailed rules, e.g. en passant moves in chess.
    • If you are making a social network app, what relationship groups are allowed? Friends? Family? Friends-of-Friends? And who can see what amongst what groups?
  • You are required to think about this topic and write at least something up for iteration 1; depending on the domain it may be a little or a lot.

Iterative requirements capture

  • You need to do several rounds on making the features/use-cases/UI sketches
  • Use each one to help refine and expand the others
  • For the projects, make several rounds for Iteration 1 and refine more in Iteration 2.

Requirements Capture for the Course Projects

We will cover what you will be doing for Iteration 1 of your projects.

Examples

We will spend a good amount of time going over example requirements, including some recent OOSE Project requirements documents.