🎯 Number Guessing Game (Python)

A simple yet polished Number Guessing Game written in Python.
This game demonstrates clean coding practices, Pythonic refactoring, type hinting, and structured documentation using PEP 8 and PEP 257 standards.

---

🧩 Project Overview

The player tries to guess a randomly chosen number within a user-defined range.
The program provides hints, tracks the number of attempts, and offers an optional “cheat mode” for debugging or fun testing.

This project was refactored to:

• Replace manual loops with Python built-ins (next(), join(), enumerate()).
• Add comprehensive docstrings for all functions.
• Include type hints for clarity and IDE/static analysis support.
• Follow PEP 8 (style) and PEP 257 (docstring) guidelines.
• Improve game structure and flow for readability and reusability.

---

⚙️ Features

✅ User-defined range for random number
✅ Cheat input (-1) reveals the secret number
✅ Hint system for higher/lower and “within 1” feedback
✅ Multiple attempts (default 4)
✅ Clean game summary for each round
✅ Play again option
✅ Fully type-annotated, well-documented code

---

🚀 How to Run

1. Clone the repository:

   git clone https://github.com/husseini2000/Number-Gussing-Game.git
   cd number-guess-game

2. Run the game:

   python number_guess.py

---

🧠 Game Flow

1. You’ll be asked to enter a lowest and highest number.
2. The computer randomly selects a number between them.
3. You’ll have 4 attempts to guess it.
4. If your guess is close (within 1), you’ll get a hint.
5. Enter -1 to reveal the answer.
6. After the round, you can choose to play again.

---

📚 Code Structure

number_guess.py
├── wel_message()          # Display welcome banner
├── number_to_guess()      # Set range and generate random number
├── get_guess()            # Collect user guesses safely
├── handle_cheat_input()   # Reveal number if user enters -1
├── give_feedback()        # Provide intelligent feedback
├── play_round()           # Control game logic per round
└── play_game()            # Run overall game loop

---

🧩 Problems Identified (Before Refactoring)

Issue	Description
🔁 Repetitive loops	Used while loops for checks that can be replaced by built-ins (next, join, any).
⚙️ Hardcoded retry logic	Maximum attempts (4) were fixed without easy modification.
🎯 Random number persistence	The same random number was reused across new rounds.
🧾 No type hints or docstrings	Functions lacked clear definitions and expected input/output documentation.
🧩 Confusing cheat logic	The “cheat mode” function name didn’t reflect its simple purpose.
🚨 Weak error handling	Non-integer input could crash the program.
🧹 Unclear flow	Replay and attempt tracking were spread across multiple functions, reducing readability.

---

💡 Improvements Implemented

Category	Improvement
🧠 Readability	All functions now have PEP 257–compliant docstrings and clear names.
🔍 Maintainability	Type hints added to every function and variable where applicable.
🧰 Pythonic Style	Replaced manual loops with next(), join(), and comprehensions.
🧩 Error Handling	Input validation ensures non-integer inputs are handled gracefully.
🎮 User Experience	Added feedback messages, summary of guesses, and emojis for engagement.
🧱 Extensibility	Structure supports future features (e.g., difficulty levels, scoring).

---

🧰 Tech Stack

• Language: Python 3.10+
• Libraries: Built-in (random, typing)
• Standards: PEP 8 (style), PEP 257 (docstrings), Type Hints (PEP 484)

---

🧪 Future Improvements

• 🧩 Difficulty Levels: Easy / Medium / Hard (dynamic range and attempts)
• 🏆 Score Tracking: Maintain win/loss stats across sessions
• 💾 Logging: Replace prints with Python’s logging for better debugging
• 🔍 Unit Testing: Add pytest tests for each function
• 💻 CLI / GUI Version: Expand into a command-line or graphical version using Tkinter or PySimpleGUI

---

🧑‍💻 Author

Al-Husseini Ahmed Abdelaleem

• 📧
• 🌐

---

🪪 License

This project is open-source and available under the MIT License.

---

🧠 Summary

This project demonstrates how a simple Python program can evolve into a clean, professional, and maintainable codebase through refactoring and adherence to best practices.

“Clean code always looks like it was written by someone who cares.” – Robert C. Martin