01-house-style/05-small-files.md

Small files

Small files

Vroq apps should prefer small, focused files with a clear responsibility.

This rule exists primarily to make code easier for ChatGPT and humans to inspect, modify, and debug.

Why small files help

Small files make it easier to:

• understand the purpose of a file quickly
• safely patch or edit code
• reduce accidental side effects
• isolate logic by responsibility

Large files make LLM edits harder and increase the chance of introducing bugs.

What "small" means

A file should generally:

• have one clear responsibility
• be readable in one screen without scrolling too much
• avoid mixing unrelated logic

Examples of good boundaries:

• reducer file
• actions file
• API client file
• feature section
• reusable component

Good splits

Good file splits usually follow real responsibilities.

Examples:

• filesReducer.js – state transitions
• filesActions.js – action creators
• FileListSection.js – UI logic for a feature section
• fileApi.js – server interaction

Avoid over-splitting

Do not create extremely tiny files for trivial helpers unless they are reused across features.

Bad example:

helpers/
  formatDate.js
  parseDate.js
  padNumber.js

If helpers are small and only used inside one feature, keep them in the feature file.

Splitting large files

If a file becomes large:

1. identify separate responsibilities 2. extract those responsibilities into new files 3. keep the main file as the orchestrator

Example:

A feature section grows too large → split out smaller sub-sections or components.

Final rule

Prefer splitting files at meaningful responsibility boundaries rather than splitting randomly just to reduce line count.