The giant file

Play this lesson

One file, 5,000 lines

Open the Hyper Shards folder and you'll find one code file that matters: game.js. It's over 5,000 lines long.

Everything is in there: the ship, the aliens, the lasers, the score, the menus, the sounds and the saves. Each time Kai and Remy asked the AI for something new, it added more code to the same file.

For comparison, most files in a well-organised project are a few hundred lines or fewer, and each one has a single job.

Why giant files break

Everything can touch everything

In a single file, any line can read or change any variable (a named value the game remembers, like score or speed).

So parts of the game end up quietly depending on each other. Programmers call this tight coupling: you can't change one part without affecting others, often in places you'd never think to look.

Here's a real kind of bug this causes.

Bug hunt

game.js
let speed = 5;function moveShip() {  ship.x += speed * input.x;}function moveAliens() {  for (const a of aliens) a.y += speed;}// AI change for "make the aliens faster":speed = 9;

Remy asked the AI to make the aliens faster. Now the ship zooms around out of control too. Which line caused it?

  1. Line 3
  2. Line 6
  3. Line 9
Show the answer

Line 9

Line 9 changes speed, but moveShip and moveAliens both read that same variable. Separate values, like shipSpeed and alienSpeed, would keep the two parts independent.

It confuses the AI too

An AI model can only pay attention to a limited amount of text at once. That working space is called its context window.

A giant file fills it with thousands of lines unrelated to your request. Even when it all fits, the lines that matter are a small piece of a huge pile. The AI can miss a second place that uses the same variable, or rewrite code that already worked.

It's like asking a friend to fix one sentence in a 300-page book they only skimmed.

Quick check

Why are AI changes to a 5,000-line file riskier than changes to a small file?

  1. The lines that matter are buried among thousands of others, so the AI can miss connections
  2. AI models refuse to read files longer than 100 lines
  3. Long files make the game run slowly, which confuses the AI
Show the answer

The lines that matter are buried among thousands of others, so the AI can miss connections

A small, focused file is easy to understand completely. In a giant file the important lines are a tiny part of the whole, so connections get missed and mistakes slip in.

Changes nobody can check

When the AI edits a giant file, the change is often spread across many places: a few lines near the top, some in the middle, some near the end.

Careful developers read every change before they keep it. But a change of 200 scattered lines is too much to read properly, so people skim it and say "looks fine".

That is exactly how bugs reach players.

The fix: code like LEGO

Real studios split their code into modules: small files that each do one job and click together like LEGO bricks. ship.js moves the ship. aliens.js runs the aliens. score.js counts points.

The numbers designers tweak all the time (speeds, health, prices) move into a data file called balance.json. Then making aliens faster means changing one number, without touching any code.

Quick check

Splitting the game into small modules makes bugs easier to find and fix, for people and for the AI.

Show the answer

True

When the score breaks, you open score.js. A small file with one job is quick to understand, and a change to it is much less likely to break the ship.

Restructure, don't restart

Should we throw game.js away and start again? No. The fun is real, and players already enjoy it.

Instead, we'll refactor: change how the code is organised without changing what the game does. Move the ship code into ship.js, play the game to check it still works, then move the next piece. We do this in Stage 2.

Bolt says: Big changes need a way to undo them if something goes wrong. Next lesson: why game_FINAL_v3.js is not that way.

Fact-checked 9 October 2026