keeping-files-small

Keeping Files Small

Overview

Large files hide bugs. A 1200-line file is a god-class waiting to happen: navigation is slow, blast radius for any change is huge, merge conflicts cluster, and reviewers skim because there's too much to read. The honest agent default is "just add it where it fits, splitting is separate work" — but the next change keeps adding, and a year later you have core.py at 2000 lines.

Core principle: A file should have one job. When it grows past ~400 lines, that's a signal it's grown a second job that should live elsewhere.

Thresholds (Rules of Thumb)

Lines	Stance
<200	Comfortable
200–400	Fine; watch the trend
400–600	Flag it — propose a split before adding more
600+	Don't add to it without splitting first

These are rough. A 500-line file of cohesive logic is fine; a 200-line file with 4 unrelated concerns is worse. Apply judgment around the limit, don't blindly enforce.

When To Use

• About to add a function/class to a file already >400 lines
• Your edit pushed a file past 600 lines
• Proposing where new code should live (greenfield decision)
• During the orientation pass when one file dwarfs the rest

Decision Flow

digraph file_size {
    "About to add to a file" [shape=diamond];
    "File <400 lines after?" [shape=diamond];
    "Just add it" [shape=box];
    "File 400–600 after?" [shape=diamond];
    "Add + flag size + propose split" [shape=box];
    "Stop. Propose split FIRST." [shape=box];

    "About to add to a file" -> "File <400 lines after?";
    "File <400 lines after?" -> "Just add it" [label="yes"];
    "File <400 lines after?" -> "File 400–600 after?" [label="no"];
    "File 400–600 after?" -> "Add + flag size + propose split" [label="yes"];
    "File 400–600 after?" -> "Stop. Propose split FIRST." [label="no — >600"];
}

How to Propose a Split

Propose, don't unilaterally restructure:

1. Identify the natural seams — function clusters that share helpers, types, or a concept.
2. Sketch the new files — names + what moves into each.
3. Show the user before doing it:

   "This file is 720 lines. I'd suggest splitting it into <fileA> (handles X) and <fileB> (handles Y). OK to do that before adding the feature?"

4. If yes — do the split as its own commit, no feature changes mixed in. Then add the new code in a follow-up commit.
5. If no — add to the existing file but flag the tech-debt explicitly in your reply.