Blackjack Game ♠

A command-line interface (CLI) implementation of the classic casino card game, Blackjack.
Try your luck by fighting against a computer dealer 💻 today and strive to get a hand closest to 21 without busting!

Explore the docs »

Table of Contents

1. About The Project
   • Project Structure
   • Technical Design
2. Design Choices
3. Getting Started
   • Installation
4. Usage
5. Acknowledgments

About The Project

Project Structure

main.py

This file contains the main entry point of the game. It initializes the game components, such as the player, dealer, and game engine, and starts the game loop.

blackjack/

This directory contains the Python package for the Blackjack game.

baseplayer.py

Defines the BasePlayer abstract class, which serves as the base class for both the player and dealer classes. It contains common functionalities and attributes shared between players and the dealer.

player.py

Contains the Player class, which represents the human player in the game. It handles player actions such as placing bets, hitting, standing, and managing the player's balance.

dealer.py

Defines the Dealer class, representing the game's computer dealer. It manages the dealer's actions during the game, such as hitting until reaching a certain threshold (the dealer's hand totals 17 or more) and revealing the face-down card.

card.py

Contains the Card class, which represents a playing card in the game. It defines the properties of a card, such as its suit, rank, and value.

deck.py

Defines the Deck class, representing a deck of playing cards used in the game. It manages the creation, shuffling, and dealing of cards.

hand.py

Contains the Hand class, which represents a player's/dealer's hand of cards. It manages the cards in the hand, computes the hand's total value, and handles adding new cards to the hand.

game.py

Defines the Game class, which manages the core logic of the Blackjack game. It orchestrates the interactions between the player, dealer, and deck, and determines the outcome of each round.

banner.py

Contains the display_banner function, which displays the ASCII art welcome message and game rules at the start of the game.

tests/

This directory contains the essential test cases for the Blackjack game to execute correctly.

Running test cases using pytest

Technical Design

Use Case Diagram

Class Diagram

Activity Diagram

(back to top)

Design Choices

• Modular Structure: The project is structured as a Python package (blackjack/) with each component (player, dealer, game logic, etc) in separate modules. This promotes code organization and reusability. Programming is much easier as the data and the code that manipulates that data are located in the same place, reducing complexity for users of that module. Based on the Single Responsibility Principle, a separate module banner was created to handle printing the welcome message and game rules.
• Object-Oriented Design: Object-oriented programming (OOP) is a style of programming that focuses on using objects to design and build applications. In this project, the game components (player, dealer, cards, etc) are implemented as classes with well-defined attributes and responsibilities. This allows for easy extensibility and maintenance. The code is focused, succinct, and understandable to humans. Following closely with the D.R.Y. or "Don't Repeat Yourself" principle, repeated, common, or shared characteristics between two or more classes (Player and Dealer) are factored out into another class (BasePlayer). Modifications to the software are thereby easier to apply and maintain, as any changes to the code common to both subclasses need only be made once in the superclass, resulting in less code and repetition overall. 
• CLI Interface: The game is implemented as a command-line interface, making it portable (run effectively in different computing environments with minimal changes) and easy to play without the need for graphical user interfaces. ASCII art is used to create a simple graphic of the playing cards on the CLI.
• Future Considerations: Further improvements in code quality will focus on the design principle of Encapsulation, where critical data and functions of the object are restricted to only within the object. This creates protection from unexpected direct changes to that data. Thus, preserving data integrity through the use of specific methods to access those attributes.

A snapshot of the interface, showing the ASCII art representation of the playing cards

(back to top)

Getting Started

To get a local copy up and running, follow these simple example steps.

Installation

1. Clone the repo

   git clone https://github.com/xlepotato/Blackjack.git

2. Install all the required dependencies

   pip install -r requirements.txt

3. Run the application by executing the following command in the directory where main.py resides in

   python main.py

(back to top)

Usage

The video below is a walkthrough of the Blackjack CLI Game.

Blackjack.mp4

(back to top)

Acknowledgments

• Harvard University, CS50P 2024

(back to top)