code-organisation

Code organisation

One principle sits under everything here: what changes together lives together. Co-locate code that changes for the same reason; separate code that changes for different reasons. Apply it at three zoom levels — system → module → file — each the same rule at a different scale.

This skill is reference. Read the level you are working at.

Placing new code

A short procedure for the recurring question "where does this go?":

1. Name its reason to change in domain language — the feature or concept it serves. Done when you can finish "this changes when ___" without naming a technology.
2. Find the home that shares that reason — the module whose other code changes on the same trigger. Done when you have checked siblings at the right zoom level, not only the file you are already in.
3. Place it, or create a sibling. If a home fits, add it there; if none fits, create a new sibling at that zoom level, named for the concept. Done when the new code's neighbours are the things that change with it.
4. Confirm the feature did not scatter — one logical change should not force edits across many directories. Done when a typical change to this feature stays inside one module.

System level — the repository

• Bounded context: split the system into self-contained models, each with its own consistent language — one context's Account need not mean another's. Map the relationships between contexts explicitly instead of letting one model sprawl across the whole system.
• Layered architecture: isolate the domain from UI, application, and infrastructure. Dependencies point inward; the domain layer holds the model and knows nothing of frameworks or persistence.
• Source tree is not the build tree: version-control inputs — source, scripts, fixtures — and never commit outputs — object files, binaries, coverage, generated docs. Build out-of-source so generated artifacts never pollute the source tree.
• Grow by component, not by accretion: a single source directory is fine until it isn't; as the project grows, divide into component directories rather than letting one directory swell.