# Project 2 How does it rank?

## Overview

In this project, you will continue with modeling the game of poker. In the previous project, you identified and counted the occurrences of different kinds of poker hands. In this project, you'll take it one step further and directly compare hands.

## Objectives

• Get some experience with refactoring
• Get more practice modularizing and using helper functions.
• Get more practice choosing good variable and function names.
• Practice testing and debugging.
• Practice analyzing running time.

## Ranking the hands

The kinds of hands we are dealing with are the same ones we had in the previous project. Here they are again, listed in order from most valuable to least valuable (see cardplayer.com for the definitions):

1. flush
2. two pair
3. pair
4. high card (all other hands)

So, a flush is better than 2 pair, which is better than a pair, etc... However, in a real game of poker, two players might have the same kind of hand. In those cases, we need to decide who has the best hand (or decide that there's a tie). The ranks of the cards determine the relative worth of two hands of the same kind. So, for example:

• A pair of aces is better than a pair of fours, because aces rank higher than fours.
• A pair of 9s and a pair of 4s is better than a pair of 9s and a pair of 3s (4s outrank 3s)
• A pair of fives and a pair of eights is better than a pair of sevens and a pair of sixes (the highest pair (eights) outranks the highest pair in the other hand (sevens)).
• A pair of 10s and a pair of 2s with a King high card outranks a pair of 10s and a pair of 2s with a 4 high card.
• A 9-high flush outranks a 4-high flush.
• A King-Queen-high flush outranks a King-Jack-high flush.

## The Mission

In this project, you will make a simple game that repeatedly:

1. Draws two new hands from a deck,
2. Shows the hands to the player, asking them which is worth more (or if they have the same value),
3. If the player was correct, they get one point and can continue.
4. If the player is incorrect, the game is over and the total score should be indicated.
5. The game is also over if there are not enough cards left to play another round.

## Project Requirements

### A required function

To support the game described above, you need a function that can take two hands and compare them. Here's the function signature and the docstring explaining its behavior:

```def compare_to(hand_a, hand_b):
"""
Determines which of two poker hands is worth more, returns positive,
negative, or zero depending on the comparison.

:param hand_a: The first hand to compare
:param hand_b: The second hand to compare
:return: a negative number if hand_a is worth LESS than hand_b, zero if
they are worth the SAME, and a
positive number if hand_a is worth MORE than hand_b
"""
```

Your function should have exactly this signature.

### Required refactoring

In addition to the satisfying the program requirements, you must also refactor your code from Project 1 for use in Project 2 (make a copy into Project 2 so you can always go back to the version you had in Project 1).

If your Project 1 did not effectively use information hiding to divide the program into separate python files, you should refactor so it does.

Any poor variable and function names should also be fixed.

In addition to these "fixing" refactorings, you should also refactor to change the internal representation for a single card:

• If you used a string to represent a card, refactor to use a tuple of two values (one for the suit, one for the rank).
• If you used a tuple or list, refactor to use a string.
• If you used some other internal representation, refactor to use one of the suggestions here.

### Unit Testing

Your compare_to function must be thoroughly unit tested, using the approaches we've discussed in class and lab. Recall that a test case is:

• Some code to run (i.e. compare_to)
• Some parameters to pass it (i.e. two hands)
• The expected result (i.e. is hand_a <, >, or == to hand_b)

Leave test functions in your code so that I can see them and run them.

Your test functions should print "PASS" or "FAIL" to indicate whether compare_to has computed the correct answer.

## Some guidance

• THINK FIRST. compare_to might sound like an easy function to write, but if you just jump right in without some careful planning, it will get out of control quickly. So, take some time to plan.
• Make incremental progress. Start with simple comparisons first, and then get more sophisticated.
• You must divide your project into multiple files (modules). Decide which parts of the internal representation needs to be hidden from others, and separate the functions that deal with those parts into their own modules.
• Use python's naming conventions for 'private' functions, so you can make helper functions in one module that are only visible in that one module.
• Remember to make your functions take parameters instead of having your functions access variables defined outside those functions.
• Avoid hacking. Especially when you are stuck on a bug:
• write out pseudocode on paper,
• draw diagrams of what's going on in memory, and
• trace through examples by hand.
Don't just make rapid changes to your code hoping that something will fix the problem. In other words, program on purpose.
• CONTINUE following the good habits I've been stressing in class:
• Use an iterative approach of code a little, test a little.
• Start with the things you know how to do, and build from there.
• Be willing to refactor. And start early enough to have time for refactoring.
• Aim for a modular design. Make helper functions and use them to make your code readable.
• Use good names for variables and functions.
• Test as you go.

## Turn it in

Turn in the project by compressing the project folder and emailing it to me. Be sure you have the honor code pledge written at the top of each python source file.

Please remember to name your project using your last name and without spaces (like CassProject2) when you create it in PyCharm.