Programming Assignment Documentation
Below is a sample programming assignment with all the required documentation. Some additional comments are shown in bold italics. These would not actually be part of the document submitted to the instructor. If you are interested the implementation of this example can be found in the Code Vault. Click on Goodies in the Code Vault index..


         

Programming Assignment X

December 21, 2012
Background Information
  In the mid 1960s a University of Cambridge mathematician, Dr. John Horton Conway, invented a mathematical game based on analogies of living organisms. He called it the Game of Life. The idea is simple. You start with a grid of any size and place "organisms" in the cells of the grid in any pattern you choose. The arrangement of organisms for each succeeding "generation" is determined by three simple rules:
  1. If an organism fewer than 2 neighboring cells it dies from loneliness in the next generation.
  2. If an organism has 4 or more neighboring cells it dies from over-crowding and disappears.
  3. If an empty cell has exactly 3 neighbors then a new organism will be born in this cell in the next generation.
During the 1960s and early 1970s computer science majors, known then as "Data Processing" majors, consumed unbelievable amounts of valuable computer time on university mainframes playing this game. You may be surprised to rediscover this game and watch the patterns that develop.
Your Assignment
  You are to create a program which simulates Conway's Game of Life. The basic requirements for this assignment are listed below. (Note: Your list of requirements in the documentation should expand on the list below. Just copying this list and calling it your requirements is NOT acceptable.)

  1. The game board shall be a minimum of 25 x 25 cells.
  2. The user should be allowed to enter a starting pattern and the number of generations to display.
  3. Each generation should be displayed on the screen until the user indicates by some means that the next generation should be calculated and displayed.
  4. Each generation should be displayed on the screen until the user indicates by some means that the next generation should be calculated and displayed.
  5. You may display the game board using simple text printed in a command prompt window or using a graphical display in an application window.

For more information on the Game of Life refer to the following sources:

  • Mathematical Games: The fantastic combinations of John Conway's new solitaire game 'Life' by Martin Gardner in Scientific American, October, 1970, pages 120-1234.

  • Mathematical Games: On cellular automata, self-reproduction, the Garden of Eden and the game of 'Life' by Martin Gardner in Scientific American, Februsry 1971, pages 112-117.

  • Execute a Google search on "conway's game of life"
Deliverables
  A standard list of deliverables (Requirements Specification Document, UML Diagram, Class Outline, and Functionality Outline) would be described here.



Based on the above description and after some careful thought, analysis, reading the articles from Scientific American, doing the recommended Google search, and discussing the project with the customer the following Requirements Specification Document was prepared.


         








Requirements Definition Document

for

Conway's Game of Life

Programming Assignment X
January 18, 2013



Prepared By
Justin A. Student
jstudent@cs.uah.edu








Prepared For
Dr. Rick Coleman, Instructor
CS 307, Object Oriented Programming
Computer Science Department
University of Alabama in Huntsville



Page Break



Table of Contents

1.0 System Overview............................1
2.0 Relevant Terms and Acronyms..................1
3.0 Requirements...............................1
      3.1 User Interface Requirements................1
      3.2 Functionality Requirements.................1
      3.3 Structural Requirements...................2
      3.4 Data Requirements.......................3







Page Break



Requirements Specification Document

Conway's Game of Life


1.0 System Overview
In the mid 1960s a University of Cambridge mathematician, Dr. John Horton Conway, invented a mathematical game based on analogies of living organisms. He called it the Game of Life. The idea is simple. You start with a grid of any size and place "organisms" in the cells of the grid in any pattern you choose. The arrangement of organisms for each succeeding "generation" is determined by three simple rules:
  1. If an organism has fewer than 2 neighboring cells it dies from loneliness in the next generation.
  2. If an organism has 4 or more neighboring cells it dies from over-crowding and disappears.
  3. If an empty cell has exactly 3 neighbors then a new organism will be born in this cell in the next generation.
During the 1960s and early 1970s computer science majors consumed unbelievable amounts of valuable computer time on university mainframes playing this game. This program demonstrates ConwayÕs Game of Life.

2.0 Relevant Terms and Acronyms
  • Cell - A single block on the game board grid.
  • Generation - The layout and arrangement of the gameboard grid after each iteration in which the three stated rules have been applied to all cells.
  • Organism - A term used to refer to a theoretical living entity occupying a single cell on the game grid.


3.0 Requirements
    3.1 User Interface Requirements
      3.1.1 Upon startup the instructions for playing shall be displayed for the user.
      3.1.2 The user shall be allowed to specify a starting layout of organisms on the gameboard by specifying the row and column of each cell to be occupied.
      3.1.3 The user shall be allowed to specify as many cells as desired up to every cell in the game grid.
      3.1.4 The user will be allowed to specify the number of generations to display.
      3.1.5 After a generation has been displayed on the screen the system will pause and wait for the user to press a key before continuing.
      3.1.6 After all generations have been displayed the user will be given the option of displaying more generations, starting a new game, or exiting the program.
      3.1.7 The gameboard shall be displayed on the screen as a 25 x 25 grid of text characters.
    3.2 Functionality Requirements
      3.2.1 At each iteration (generation) the game engine will scan all cells in the grid and check the status of cells to the north-west, north, north-east, east, south-east, south, south-west, and west of the current cell if such a neighboring cell exists.
      3.2.2 The status of neighboring cells shall be defined as "occupied" or "empty".
      3.2.3 If the status of a cell being evaluated is "occupied" and it is found to have two or fewer neighboring cells it will be marked as being "empty" in the next generation.
      3.2.4 If the status of a cell being evaluated is "occupied" and it is found to have four or more neighboring cells it will be marked as being "empty" in the next generation.
      3.2.5 If the status of a cell being evaluated is "empty" and it is found to have exactly three neighboring cells it will be marked as being "occupied" in the next generation.
      3.2.6 Any cell being evaluated which does not match any of the criteria in requirements 3.2.3, 3.2.4, or 3.2.5 shall have its status unchanged in the next generation.
      3.2.7 The application of the rules to one cell in the grid shall not alter the effects of the layout in subsequent cells in the same iteration, e.g. if the cell in row X, column Y is found to disappear in the subsequent generation then applying the three rules to the cell in row X+1, column Y will not treat the cell in row X, column Y as already empty, but still occupied by the cell that will die in the next generation.
      3.2.8 After the next state of all cells has been calculated the gameboard layout for the next generation shall be updated appropriately to record the calculated changes.
      3.2.9 After the next state of all cells has been updated appropriately the gameboard will be displayed on the screen.


1
Page Break
    3.3 Structural Requirements
      3.3.1 The gameboard shall be implemented as a 25 x 25 grid of text characters.
      3.3.2 The gameboard shall be represented internally using an appropriate data structure which will represent a two dimensional array.


    3.4 Data Requirements
      3.4.1 Specific text characters will be used to represent an occupied and unoccupied cell, e.g. 'O' can represent a cell occupied by an organism.


2
Page Break


Note that originally the option of displaying the game in a GUI (Graphical User Interface) with neat drawings would have really looked good, but the programmer decided that given the time limits for the project, and her lack of experience with building GUIs using MS Visual C++ that this would not be done. This illustrates that one of the important parts of requirements analysis is not only to decide on what the software should do, but also to decide what it SHOULD NOT do. Or, at least what it should not do in version 1.0. Save that for later when you can convenience the customers that they should pay for the New and Improved version 2.0 ;-)





After studying the requirements and carefully planning the structure and layout of this assignment a preliminary class diagram was prepared using StarUML.


Preliminary Class Diagram

GameOfLifeMain() This function, not shown in the class diagram, will just be responsible for creating an instance of the GameOfLife class and then calling the InitGame and PlayGame functions sequentially. All other functionality will be handles by the two main classes.

GameOfLifeThis class will be the central controller class. It will handle all user interaction and will be responsible for controlling when the GameBoard class executes any of its functionality.

GameBoardThis class will be responsible for storing the current location and status of all organisms. It will be responsible also for calculating the layout of the next generation of organisms and for drawing the gameboard when told to do so by the GameOfLife class.




This page is still under construction