024-snake/docs/business-case.md

Business Case: Snake Game (Day 24)

Metadata

Key	Value
ID	BC-001
CrossReference	SA-001, DICT-001
Language	en
Domain	it

Version History

Date	Status	Author	Reviewer	Change	Commit
2026-10-13	Accepted	Jens Tirsvad Nielsen	AI as stand-in for S01	Initial version, reviewed in RC-001 (Go)	pending

---

Executive Summary

Snake Game (Day 24) is the day-24 assignment of Udemy's 100 Days of Code: The Complete Python Pro Bootcamp: the snake game of days 20 and 21 gets a high score that survives between games. Day 24 teaches the local file system and reading and writing files with open and the with keyword. Applied to the game, the lectures change four things: the scoreboard keeps a high_score next to the score, the game no longer ends on a collision but resets the snake and the score and goes on, the high score is read from and written to the file data.txt, and so it is still there when the game is started again.

This repository starts from the finished game of the day-21 repository 021-snake-game (the same way that repository started from 020-snake-game), changes it as the day-24 lectures describe, and gives it the identity of this repository: name, README, description, topics and a wiki in English, Danish and Bahasa Melayu. The work is planned in five milestones, each delivered by one branch and one pull request. The game has no runtime dependencies.

Methodological and Standards Foundation

• Process: the Software Quality Assurance (SQA) and Quality Criteria (QC) framework mounted at framework/: Business Case, Stakeholder Analysis, Project Plan, milestones, tasks synced as issues, then code, each step reviewed before the next. Analysis follows Larman, Applying UML and Patterns.
• Quality model: ISO/IEC 25010:2023; every QC criterion is tagged with a characteristic of it.
• Code: Python Enhancement Proposals (PEP) 8, 257 and 484, reviewed against QC-PY-001; comments in Doxygen style; tests with pytest.
• Domain terms: the lectures' own terms and names, recorded in the Domain Dictionary DICT-001: screen, snake, segment, head, food, score, scoreboard, high score, reset, game over, file, mode (r, w, a), with, and the names Snake, Food, Scoreboard, reset, high_score, update_scoreboard, increase_score.

Problem Statement

• The high score of the lectures lives in a variable, so it is zero again each time the game is started; the lecture itself calls this out as a flaw.
• A game that stops at the first collision cannot be played again without starting the program again, so a high score has nothing to compete against.
• Reading and writing a file is easy to get subtly wrong: a file left open, a text that is not a number, a file that does not exist yet. The lecture shows the happy path only.
• A turtle program opens a window, so it is normally not tested, and the file handling needs tests that touch no real window and do not overwrite the player's real high score.
• A repository without a description, topics, README or wiki is hard to find and to judge for the people who browse for ideas.

Business Opportunity

A finished, reproducible repository shows the path from the day-24 lectures to documented, tested code. Starting from the finished day-21 game saves the rebuild, so the effort goes into what is new: continuous play, the high score and its persistence, and the testing of the file handling. It can be compared with the solutions of other participants and shared.

Objectives

#	Objective
1	Keep the behaviour of the day-21 base: a 600 by 600 black window titled "My Snake Game"; a snake of three segments that moves by itself and turns with the arrow keys without reversing; food that is eaten, makes the snake longer and raises the score
2	Deliver the high score of the lectures: Scoreboard has a high_score attribute that starts at the stored value, and the scoreboard shows Score: <score> High Score: <high_score>
3	Deliver continuous play: Scoreboard.game_over is replaced by Scoreboard.reset, which sets high_score to the score when the score is higher, sets the score to 0 and writes the scoreboard again; touching the wall or the tail calls reset of the scoreboard and of the snake and the game goes on
4	Deliver Snake.reset: every segment is moved off the screen, the segment list is emptied, the snake is created again at the starting positions and head is the first new segment
5	Deliver the persistence of the lectures: the high score is read from data.txt with with open(...) when the scoreboard is made and written to it, as text, when a new high score is reached; the value is still there after the game is closed and started again
6	Handle the file robustly where the lecture does not: a missing file is created with 0, and a file that does not hold a whole number is treated as 0
7	Keep the assignment's structure and names (Snake, Food, Scoreboard, create_snake, add_segment, extend, move, reset, up, down, left, right, segments, head, high_score, update_scoreboard, increase_score, game_is_on), constants in constants.py
8	Provide a reproducible environment: Python 3.13 or newer, a local .venv, a pyproject.toml, and zero runtime dependencies
9	Prove the behaviour with pytest tests that need no display and never touch the player's real data.txt
10	Document the project: Doxygen comments in the source with a Doxyfile, and a README with set-up instructions for Windows PowerShell, Linux Debian and macOS
11	Keep every step traceable: one branch and one pull request per milestone, each pull request closing the issues it completes
12	Publish the repository with a description and topics, and a wiki in English, Danish and Bahasa Melayu

Scope

In Scope

• Adopting the finished game of 021-snake-game (source, tests, configuration, continuous integration workflow) as the base of this repository, and recording every difference from it.
• The day-24 lectures about the snake game: the high score attribute, reset instead of game_over, continuous play, Snake.reset, and reading and writing data.txt.
• Constants in constants.py; source in src/, tests in tests/, documents in docs/.
• pyproject.toml, Python .gitignore, Doxyfile, README.md following the Product Owner's template, a continuous integration (CI) workflow.
• Repository description and topics on the git host.
• A wiki in English, Danish and Bahasa Melayu, in the form of the wiki of TirSystem/github-action.

Out of Scope

• The day-24 project that follows the snake game, the personalised letters (mail merge); it is a separate program and gets its own repository if S01 wants it (see the open issues of PP-001).
• File paths and directories beyond the single file data.txt; the lecture announces them as the next topic.
• Anything the lectures do not cover: sound, a menu, a list of players, levels, configurable speed or window size.
• Keeping this repository and 021-snake-game in step after today.
• Packaging for or publishing to the Python Package Index (PyPI), and runtime dependencies of any kind.
• Using or testing the tokens in .env; the file is for personal use only and is never imported by the project.

Expected Benefits

Tangible Benefits

• A finished game (day 24) with a high score that survives between games, running with one command after the README steps.
• A test suite that runs in continuous integration without a display and without touching a real high score file.
• Generated source documentation.
• A repository page with description, topics, README and a three-language wiki.

Intangible Benefits

• Practice with file handling, the with statement and the string-to-integer conversion, which is the aim of the lectures.
• A pattern for the following days of the course.
• Confidence from a step-by-step, reviewed delivery.

Strategic Alignment

The project supports the participant's goal of finishing the bootcamp with repositories that other people can read, run and learn from, and it exercises the framework's rule that planning, review and code stay in step.

Success Criteria

#	Criterion	Target	Measure
1	The day-21 behaviour is kept	Window, snake, steering, food, eating and score behave as in 021-snake-game	Manual run by S01 against the Go/No-Go list of MIL-002, plus the matching tests
2	The scoreboard shows both scores	The text reads Score: 0 High Score: 0 at the start and updates when the score or the high score changes	Manual run by S01 against the Go/No-Go list of MIL-003, plus the matching tests
3	A collision resets and play continues	At the wall or the tail the score becomes 0, the snake is back at the three starting positions, the old segments are off the screen, and the game goes on; the high score is the largest score reached	Manual run by S01 against the Go/No-Go list of MIL-003, plus the matching tests
4	The high score persists	After a new high score the file data.txt holds it as text; after closing and starting the game it is shown again	Manual run by S01 against the Go/No-Go list of MIL-004, plus the matching tests
5	The file handling is robust	A missing file is created holding 0; an empty or non-numeric file reads as 0; the file is always closed (with)	Matching tests, review of src/
6	Tests are green and need no display	100% of tests pass; 0 tests open a window; 0 tests read or write the real data.txt	pytest exit code 0 locally and in CI
7	The set-up steps work	A fresh clone reaches a green pytest by following the README alone, on Windows PowerShell (by S01) and on Linux (by CI)	One run per operating system, recorded in the pull request
8	Source documentation builds	doxygen Doxyfile ends with 0 warnings	Doxygen output
9	No runtime dependencies	0 entries in [project].dependencies	pyproject.toml
10	Names follow the assignment	100% of the names listed in objective 7 exist with that spelling	Review of src/ against objective 7
11	Steps are traceable	5 of 5 milestones merged by pull request, each description with one Closes #N line per completed issue	Pull request list and issue states
12	The repository page is complete	Non-empty description, at least 5 topics, and the wiki pages Home, Home.da and Home.ms	Git host
13	The base is adopted without hidden change	Every difference between the adopted files and 021-snake-game is listed in the pull request that introduces it	Pull request descriptions

Risks

Risk	Impact	Mitigation
tkinter is missing from the Python installation (typical on Debian)	The game cannot start	README lists python3-tk for Debian; the tests install a fake turtle module and need no tkinter
Debian 12 ships Python 3.11, below the required 3.13	Linux set-up fails	README states Debian 13 or newer, or a separately installed Python 3.13
A turtle window cannot be opened in continuous integration	The tests cannot cover the game	Only main opens a window; the classes are tested with fakes, as in the base
A test overwrites the player's real data.txt	The player loses a high score	The path of the file is a parameter with the constant as default; tests pass a temporary path (pytest tmp_path)
data.txt is resolved against the current working directory, so the game started from another folder finds another file	The high score seems to be lost	Decided in MIL-004 and recorded in an open issue of PP-001; the lecture's plain file name is the default
The file is missing, empty or damaged	The game crashes at start	Objective 6: read as 0 and create the file; covered by tests
Author and reviewer are the same person (S01)	A defect can pass review unnoticed	Review against the QC checklists, record each review as an RC-*, and let the pull request be the second look
The lectures are available only as the summaries in the request	The game differs from the video	S01 compares the finished game with the video at the MIL-003 and MIL-004 Go/No-Go
The adopted files drift away from 021-snake-game	A fix made in one repository is missing in the other	Out of scope by decision; each pull request lists the differences from the base
Tokens in .env leak into the repository	Credentials exposed	.env is in .gitignore, is never imported, and is not part of any task
The wiki is published with a secret of the organization that may be missing	The wiki stays empty	The pages are files in wiki/ of the pull request; the marker wiki/.publish makes the instance's workflow publish them; a missing secret is reported, not worked around

Assumptions

• Python 3.13 or newer with tkinter is available on the machines that run the game.
• S01 is the only person who reviews and accepts artifacts.
• The git host is the Tirsvad Gitea instance, and its issues and milestones are used for tracking.
• The day-24 lecture summaries in the request are the specification of day 24; the video is the tie-breaker when a detail is missing.
• The finished main of 021-snake-game is correct as far as its own tests and review records show, and is the base for every file that the milestones adopt; S01 pointed to it in chat on 2026-10-13.
• The look of the snake (light green body, dark green head with a mouth) of 021-snake-game is kept.
• The wiki of the repository is enabled and has no page yet.

Constraints

• Python 3.13 or newer, in a virtual environment (venv).
• pytest for tests; constants.py for constants; pyproject.toml for project configuration; a Python .gitignore; Doxygen comments in the source and a Doxyfile.
• Folder structure src/, tests/, docs/.
• No runtime dependencies unless needed.
• Plan window from 2026-10-14 to 2026-10-25 (proposed, see PP-001).
• S01 switched on autonomous mode in chat on 2026-10-13: S01's acceptance of the plan is the request to commit, push, open and merge the pull requests; the assistant's reviews are then not independent (see AGENTS.md, Modes).
• The plan gate holds: no file under src/ or tests/ before an accepted, reviewed milestone that lists the task.

Cost–Benefit Assessment

The assessment is qualitative on purpose: this is an unpaid learning project with one participant, so money does not measure either side.

Costs	Benefits
About ten days of S01's spare time, most of it review of the planning documents	A finished and shareable repository (objectives 1 to 12)
Two repositories that hold similar code and can drift apart	No rebuild of a game that already exists and is tested
Doxygen and pytest as development tools (not runtime)	Source documentation and automatic checks

Stakeholders

Stakeholder ID (SA)	Interest in this project
S01	Wants a correct, tested and documented solution of the assignment: objectives 1 to 12
S02	Needs readable, runnable code with the assignment's names and README instructions (objectives 2 to 4, 7, 8 and 10)
S03	Needs a clear repository page and nothing to install (objectives 8, 10 and 12)

Recommendation

Proceed — the work is small (adopt a finished and tested base, add the high score, continuous play and the file, document and publish), the cost is about ten days of the Product Owner's spare time, and the result is a reusable, documented repository.

---