CS21 Lab 7: Memory Game (TDD)

Design is due Saturday, March 28, before midnight

Full Implementation is due Sunday, April 5, before midnight

Due date was extended due to network outage this week.

Goals

  • practice using Top-Down Design

  • write a complex program, with multiple functions, from scratch

Notes

Please read through the entire lab before starting!

This is a two-part lab, split over two weeks. For the first week you will focus on using top-down design to create the overall structure for the program. Once your proposed structure has been reviewed and approved by your professor or lab instructor, you will use bottom-up implementation to complete the full program.

You have two weeks to complete the full program. The first week is for the design, and the second for the full program. Your initial top-down design is due this Saturday (March 28) and the full implementation the following week (April 4). It is highly recommended that you submit your top-down design as soon as is possible so that we have time to give you feedback before you begin your full implementation. If you submit your design on the last day at midnight, it might take us a few days to get to it and send you comments.

memory game

As a kid I loved playing a memory game with cards: place as many pairs of cards as you want face down on a table, then take turns turning over two cards at a time. If the two cards match (both red twos, or black fives, etc), you get to keep the pair. If they don’t match, turn them back face down, and let the other player pick two cards.

For this lab we’re going to write a terminal-based memory card game, allowing a single user to select two cards at a time and see if they match.

Examples and Program Requirements

Here are a few examples of the running program, to help you see how things should work. Pay attention to how the game proceeds, and how input from the user is handled. As you can see from these examples, we have simplified the game a bit, since we’re using a terminal screen to display the game. For example, we don’t clear the screen between turns, making it easy to view past turns. See the Extra Challenges below if you have time and want to make a more realistic game. We are also using a deck of "bird" cards.

You have some freedom in how you want your game to look. Here are our requirements for the full program:

  • the program should print out adequate instructions throughout the game (see examples)

  • the program starts with 10 cards (5 pairs) face down

  • the user selects a card and is shown what that card is

  • the user selects a second card and is shown that card and if it’s a match or not

  • playing the game again should present the user with a different setup (i.e., the cards should be randomly shuffled each game)

  • the program should handle invalid user input properly by re-asking for a value (see Example 2)

  • the program should handle invalid selections (e.g., same card) by not doing them (and telling the user it was an invalid selection)

  • the game should end once all cards have been matched

  • when the game ends display a status message showing how many cards matched, how many turns it took, and a message based on those numbers (e.g., 10 cards in 5 turns: super!, 10 cards in 8 turns: not bad, 10 cards in 35 turns: better luck next time)

  • all output should be clean and easy to read

Top-Down Design Requirements

You should complete your top-down design (TDD), submit it (run handin21), and obtain feedback on it before beginning the full game implementation. Special procedures for this two-week lab:

  • create your design in design-memorygame.py first

  • after you have a working design (see example below), run handin21 to turn it in! Then send a short email to tdd@cs.swarthmore.edu, letting us know your design is done. We will take a look at each design and send you comments (usually within a day or two). If the design is incomplete or insufficient, you may be asked to submit a second design.

  • after you have the design done and have heard back from us, please copy the design file to memorygame.py and implement the full game in memorygame.py (i.e., leave design-memorygame.py as is!)

    cp design-memorygame.py memorygame.py

  • please ensure your design meets the following requirements before submitting:

    • main() should be completely written, and should perform high-level steps without focusing on details

    • main() should call the functions you create in your design, in the appropriate order, and with arguments that match parameters. Return values should be saved in main(), even if you don’t do anything with them yet.

    • all functions should be stubbed out with parameters, a block comment, and a return statement. They don’t need to actually do anything yet, except possibly call other functions.

    • if your function is meant to return something, you should return a dummy value of the appropriate type (e.g., return 0 for an int, or [1,2,3] for a list).

    • your design should have several functions. Each function should be function worthy (i.e., not a trivial task) and also demonstrate encapsulation (one clearly defined purpose).

    • the design should run without syntax errors (although it doesn’t play the full game yet)

Your goal for the design is to completely write main(), such that it won’t need to change much as you implement and test all of the other functions.

If you are confused about how the top-down design should look, please see the following examples of a design and full program for a simple guessing game program.

tips

Note: some of these tips may not be needed until you implement the full program in the second week of this lab, but are included here to help you with the design.

data structure

We suggest using a python list of strings, something like this:

birds = ["finch","robin","crane","macaw","stork","egret","raven"]

You can make your cards something else if you want (countries, colors, cs profs, etc), but it is easier if all strings in the list have the same length.

shuffle(L)

The random library includes a shuffle(L) function that, given a python list, will shuffle the items in the list (in place). You are welcome to use the shuffle() function to randomize your cards at the beginning of the game.

string formatting

Using the width specifier will probably help you line up all of your cards. In the following example, using %10s means strings with fewer than 10 characters are padded on the left with spaces:

>>> names = ["jeffrey", "lisa", "aline", "0123456789"]
>>> for i in range(len(names)):
...    print("===%10s===" % (names[i]))
...
===   jeffrey===
===      lisa===
===     aline===
===0123456789===

testing the game

Once you start working on the game implementation, being able to quickly win makes debugging easier and faster. Write your program so you can easily change the number of cards. Playing the game with only 4 cards is much faster than playing with 10 cards.

Extra Challenges

These will not affect your grade or gain you extra points. They are included just as extra challenges, if you are interested (and have already finished the entire game).

  • allow the user to quit the game early by entering a special character (e.g., 'q')

  • allow the user to pick how many cards to use, a number between 6 and 20

  • if using more than 10 cards, display a second row of cards (see video below)

  • clear the screen after each pair of cards is chosen. For this you can use import os and os.system('clear') when necessary (also see video below)

Extra Challenge Video
Another Extra Challenge Video

Answer the Questionnaire

Please edit the Questions-07.txt file in your cs21/labs/07 directory and answer the questions in that file.

Once you’re done with that, run handin21 again.

Turning in your labs…​.

Remember to run handin21 to turn in your lab files! You may run handin21 as many times as you want. Each time it will turn in any new work. We recommend running handin21 after you complete each program or after you complete significant work on any one program.