Requirements - luney-sp-76/SaveThePlanetSE1 GitHub Wiki

Navigation:
This page: Requirements

Our Kanban Board

1. Requirements

The Core Requirements for the project are found in the README.MD file and the [Functional Requirements](Requirements/Functional Requirements) section

CSC7083 Software Engineering Project
‘Save Our Planet’
Deliver a well-designed and well-documented working system that satisfies the customer requirements.
Requirements
The emphasis in this project is on the process of requirements analysis, system design, software implementation and system testing that delivers reliable and appropriate functionality.
The project will demonstrate your understanding of and ability to practice object-oriented software engineering principles and your ability to work in a software engineering team.

The system requirements, analysis and system design, will be represented in the graphical notation known as the Unified Modelling Language (UML).
The project will be a ‘use case driven’ development process, in which each use case describes “a set of sequences of actions, including variants, that a system performs to yield an observable result of value to an actor” (Booch, Rumbaugh and Jacobson).
The system to be developed is a virtual board game – but it does not have an elaborate graphical user interface. Instead, the game is to be played via the console mode of the software development package (e.g. Eclipse). The system will also have its own distinctive theme, based on caring for the planet. Think of investing in different environmentally-friendly schemes, developing various aspects of these, generating income from them or devoting resources to them. Rather than use cash for your transactions, you might want to think about allocating some other resources – people, equipment, know-how, time-and-effort. It’s your job to think through and apply the ‘metaphor’ you want to use in your game.
The simple console-based interface allows you to concentrate on the process of determining and designing the underlying object-oriented system rather than focus on visual or audio effects. The system uses English phrases to convey the game state and ask its players what they want to do next. Though you don’t have to develop a speech user interface (SUI), imagine a game where the state of play can be conveyed in words alone – whether a new development is being reported or the current state of play summarised.
A game of this kind might start and unfold in the following manner (the example is not taken from Save Our Planet though the behaviour of your game will be broadly similar):

1 Very important: each use case is represented as a single ellipse, and each use case is a complete set of sequences of actions in itself. For example, a single use case might describe everything an actor does in order to Register with a system:
enter first name, enter family name, enter DOB, enter house number, etc., etc. (note: this probably won’t be one of the use cases in your Save Our Planet Game!). All those steps are represented by a single use case and a single ellipse. An ellipse in a diagram contains the name of a use case. The corresponding use case description describes what the sequence (flow) of actions would normally be to achieve a desirable outcome, which is the whole point of the use case! For example, if the Register use case executes successfully, the actor will have become a registered user of the system – that is the desirable outcome. However, the description of the Register use case should also say what alternative sequences (flows) are needed at particular steps under certain circumstances – what happens, for instance, if an actor enters an exclamation mark for the house number during registration!. In other words, the use case descriptions convey much more information that the ovals in the diagram. Several use cases (several ellipses) will typically appear in a single use case diagram. Each ellipse represents a use case. Each use case must have a description. Never use a use-case ellipse to represent a single step in a chain or sequence of steps. A single ellipse IS a set of sequences of steps – normal flow and alternative flows – that achieves some important outcome! So aim to have few rather than many ellipses in your diagram: each ellipse represents a use case, and each use case requires a description of the steps it involves! There are no bonus points for a jumble of ellipses. An ellipse without a description is pointless. Decide the important outcomes. Name the use cases accordingly. Describe the use cases carefully.

What is the first player’s name? Janet
What is the second player’s name? John

Janet, would you like to roll? y/n: y

OK, Janet, you’ve rolled a 5 and a 6 – that makes 11.
You’ve landed on Square X. No one is in charge of that yet.
Do you want to invest in this and take charge (y/n)? y

Investment made.
Your old balance was 1500 points.
Your new balance is 1440.

Janet is now in charge of Square X

John, would you like to roll? y/n: [...]

Because the game is to be conducted in a natural language only (i.e. English phrases that convey the state of play, etc.), it will have fewer ‘squares’ than a traditional board game. Therefore, a separate guide is required. The game you will develop is meant to be very, very simple – literally like the little set of boxes below. (You should not produce a booklet about your game.) The purpose of the game guide is to show the position and attributes of the squares. You may create your game guide with any suitable drawing tool, such as PowerPoint or the drawing tool of Word, and should include this in the Requirements Analysis section of the Short PDF Report [see below]).
Again, the example shown is NOT for Save Our Planet, nor is it necessarily complete; it is intended only to represent the manner in which such a graphical representation might be drawn. Remember that, through the comments, it writes to the console, the software itself must remind players of their positions and their custodianship of squares and the properties of those squares.

Your game will have many of the features of a board game but in a much simpler form. Within the constraints of the ‘natural language interface’, your customer’s core requirements are set out below, between the dashed lines (------).

Remember, this is what your customer is asking for and expects to be delivered. You can realise these requirements while giving them your own creative ‘twist’ – but your customer is not asking for additional features (e.g. the customer does not want more squares, more types of squares, or more players than the number stipulated below). On the other hand, where checks are needed to ensure that the game is usable (for example, to avoid a situation where two players have the same name), such checks should be implemented, even if they are not explicitly requested. That is simply good design.

Similarly, although your customer has no immediate plans to ‘adapt’ or ‘upgrade’ Save Our Planet to a more specialised or more complex game, there may be (OO) design features that, with only a little additional effort, you can incorporate ‘behind the scenes’ to make your system more maintainable and extensible – e.g. a well-designed game would allow the number of squares or the maximum number of players to be increased or reduced easily in the code, should that requirement arise in future. Good software design not only meets current requirements but can easily accommodate change. [N.B. A separate user interface for significant re-configuration of the game is NOT one of the requirements for Save Our Planet.]


Here are the core requirements.
Your game should do the following and have the following features (or do/have something that is functionally/conceptually equivalent):

**Functional Requirements **

-------------------------------------------------------------------------------------------

1. The game has up to four players, and their names should be entered at the beginning of the gameplay.
   
2. The players take turns. They throw two virtual dice at a time during their turn.
   
3. Players are told where they have landed and their obligations or opportunities. Then, where appropriate, they may indicate their choice of action. For example, dedicating some of their Investment Fund resources may ‘take charge’ of a square no one else owns. If a player lands on a square no one owns, but they don’t want to take charge of it themselves, it may be offered at the usual cost to another player.
   
4. If a player’s resources have changed, the system indicates the reason for the change and announces the player’s new ‘balance’ (e.g. the ‘funds’ or ‘credits’ that are still available).
   
5. There is a start square, where players pick up their ‘resources’ (it’s your choice what the ‘resources’ represent – and you should be inventive with the square’s name – this is the equivalent of a ‘Collect X as you pass Go’ square). Next, there is a square on the board where nothing happens – again, you decide what it is called in your game.
   
6. There are four ‘fields’, two consisting of three ‘areas’ and two consisting of two ‘areas’ respectively. A number of related areas form a ‘field’ in Save Our Planet. You decide what the fields are called and what they represent. For example, Renewable Energy might be a ‘field’. Different areas make up a field: Hydroelectricity might be an area in the field of Renewable Energy [say it out loud, and see if it makes sense!]. You decide what the fields are in your game and what areas they will include. One of the two-area fields is the most costly field on the board to acquire and resource; another two-area field is the least costly field to acquire and resource.
   
7. Before you can develop an area within a field, you must own/manage/’be in charge of’ (you decide what ‘custodianship’ means!) the whole field – and on your turn you can develop an area in a field that you already own even if you are not positioned on that area.
   
8. Decide what development is called, what it represents, and how much it costs in your game; others might have to pay you or invest in it to use it. (Again, you decide the nature and the significance of the transactions between players.) Three ‘developments’ are needed before you can establish (and pay for, or otherwise ‘resource’) the equivalent of a ‘major development’ (again, you decide what this represents and what it costs).
   
9. Not only is there a cost associated with developing areas within fields: when you land on an area but do not ‘own’ it yourself, you have to give up some of your resources for it – the more developed the area, the greater the resource consumed.
   
10. Decide what happens when one player runs out of resources. Are they the winner or the loser? It’s your choice. If one player no longer wants to play, the game ends. In both cases (no resources left; not wanting to play), the amount of resource each player holds is shown. There is no need to convert ‘developments’, etc., to an equivalent value in your ‘resource units’. Find forms of words that express the outcome of the game in a manner appropriate to the overall style of your version of Save Our Planet. Is winning a matter of amassing resources from other players, or should our Save-Our-Planet hero be aiming to give all that they have (and more) to support the worthy ventures of a fellow eco-warrior?
    ---------------------------------------------------------------------------------------------
    Deliverables
    A. Working System
    The working system that satisfies the requirements between the dashed lines (------) should be developed to complete the coursework along with the project report and a demonstration video (specified in the section below). (20 marks)
    A system that satisfies all the requirements between the dashed lines (---------) attracts up to 10 overall project marks. In addition, up to 10 additional marks are available for systems that, within the constraints of the text user interface, deliver the required functionality in a manner that demonstrates excellent usability, including clear, timely and engaging interaction with the players, and a novel and coherent interpretation of the Save Our Planet theme. (Though it is sometimes fun, elaborate ‘pretty printing’ – i.e. making shapes, etc., out of the text – is not required for this system [remember the SUI/’words-alone’ guideline above!]).
    
    B. Short PDF Report
    Each team should produce a short PDF Report to accompany their game.
    
    At the start of the PDF Report, teams must include their Peer Assessment Form, in which team members assess and agree on the contribution that their fellow team members have made to the project. The Peer Assessment scores calculate each student’s individual mark from the raw mark that the assessor gives to this deliverable, which will be common for the project group. Teams should meet in good time to conduct the Peer Assessment exercise. Probably, one week before submitting the project is a good time to avoid any last-minute dispute in the team.
    
    The main body of the report (excluding appendices and the peer assessment) should not exceed 20 pages.
    Individual team members should place their initials (e.g. [A.B.; C.D.]) next to the sections for which they were the principal authors. The main body of the report should include the following sections.
    
    A Requirements Analysis section, comprising a UML Use Case Diagram and an accompanying Use Case Descriptions. The Diagram and Descriptions should concentrate on the main sets of sequences of actions that will be realised by the system. Plan your game’s behaviour so that it can cope if problems arise (e.g. what happens if two players enter the same name?), and in such circumstances make sure you have an appropriate alternative flow or an extending use case. In your Requirements Analysis, include your guide to the virtual ‘board’ on which your game is played (remember: this graphical representation is for guidance only; it will NOT be implemented as a GUI in this text-only system!). (30 marks)
    
    

A Realisation section, comprising several UML Sequence Diagrams with a brief written commentary. The sequence diagrams show how your software components make method calls to each other, and interact with the players, in order to realise the behaviour of the main use cases described in the previous section. Remember: any class that you show at the top of lifeline in a sequence diagram should also appear somewhere in your class diagram. (20 marks)

A Design section, comprising a UML Class Diagram, that describes the system components. The class diagram will correspond closely to the coded implementation of the game; it should show classes and methods that support the sequences of method calls described in the previous section. Again, provide a brief written commentary on your design, pointing out any instances of good design where you have considered questions of maintainability and extensibility. (20 marks)

Adherence to process should be documented in appendices. Place a Test Plan for the implemented system in Appendix I (your main Test Plan may take the form of an Acceptance Plan, like the one shown in Chapter 12 of your lecture notes, and you may provide evidence of unit testing as well – for example screen dumps showing that unit tests ran successfully). A set of weekly Team Minutes should be placed in Appendix II – use the Weekly Team minutes template provided on Canvas under Activity Plan and Project. GitLab version management software should be used to facilitate collaborative working: place evidence of the team’s use of GitLab (e.g. a screen dump of GitLab’s Contributors graphs; a representative sample of screen dumps from GitLab’s Commit history) in Appendix III. Other evidence of day-to-day project management (e.g. brief descriptions of backlog items and tasks, with estimates; <br. screen dumps of sprint backlog tables and team/team-member burndown charts, etc.) should be placed in Appendix IV. (10 marks)

Video of Project Demonstration

In addition, teams are required to produce a video (with commentary; approx. 5 minutes) of their working system. The video should illustrate the working implementation of the functionality requested above. The video must be in MP4 format and must run in VLC software: check that it does by using the software available at videolan. This video is required for review by the external examiner. The project cannot be marked if the video is not submitted or cannot be played by the assessors. The video should be uploaded to Canvas at the same time as the working system is uploaded.

Note: These are group deliverables to be produced and agreed upon by project teams. Once the team’s Git Lab space becomes available, authors (whether of code or documentation) should upload their work regularly to appropriate team folders.

Some samples of UML notation
It is important to look at the full module notes and recommended texts in order to appreciate the variety of ways in which the UML notation and accompanying descriptions may be used. The descriptions and diagrams below are working samples only and do not represent a full solution. Choose use case names, write use case descriptions, and create classes and objects that suit the software you are developing – your diagrams and descriptions will be different from the examples shown below! e.g. From Chapter 4 of the Module Notes:
e.g. From Chapter 5 of the Module Notes (though this chapter is about Analysis, class and sequence diagrams are used to document design too!):

Flow of Events for the Select Element use-case
Objective To select an element in the workspace Precondition There is an active diagram containing at least 1 element **Main Flow **

1. The user selects the selection tool (if necessary)
   
2. The user moves the cursor over an element
   
3. The user presses the mouse button
   
4. The element becomes selected and the control points are displayed
   
5. The user releases the mouse button
   Alternative Flows
   At 3, there may not be an element. In this case no element is selected
   At 3, the element may already be selected. In this case, it remains selected
   Post-condition The element is selected and its control points are displayed