Organising Modules
In this pack:
sizing,
notation,
rule strictness.
Overview
A module is a group of classes with one public interface; a package or
a folder is how the code spells it. How a codebase is divided into
modules decides how much of it one change touches, what can be built
and tested apart, and how many teams must agree before a release. This
skill groups classes by business capability, keeps the dependencies
between modules free of cycles, makes a module that many others depend
on abstract, gives every module a small public interface the build
enforces, and keeps one deployable unit until a module must live apart.
Scheduling, billing and clinical records are capabilities of the
clinic, and the layers of each sit inside its module.
When to use
- You are deciding how to group classes into packages or folders.
- Two modules import each other, directly or through a third.
- A module many others depend on changes in most releases.
- One module uses a class or a table that belongs to another.
- You are choosing between one deployable unit and separate services.
- The build has no check on which module may depend on which.
When not to use
- The question is how tightly two parts are tied, or how to measure
it: that is
diagnosing coupling.
- The question is the layers inside one module and which way they
depend: that is
layering the system.
- The question is where one team's model ends and another's begins:
that is
bounding contexts.
- The code is one small module with one capability and one team.
Leave it as it is.
Core rules
Default. Make the top-level modules business capabilities, such as
scheduling, billing and clinical records, not technical kinds such
as controllers, services and repositories. The layers of each
capability then sit inside its module, so a change to one capability
touches one module.
The exception is a small application with one capability, where one
module with a folder per layer is enough.
Rule. Put classes that change for the same reason and are used
together in one module, and keep apart classes that are not used
together. A module that bundles unrelated classes makes every user
depend on, rebuild and retest all of them for a change to one. A
capability spread over several modules makes one change touch them
all.
Judgement. Weigh three pulls on a module's contents: classes that
change together, classes that are used together, and classes
released together under one version for others to reuse. Early in
a project, group for change. Once other teams reuse a module through
its releases, group for reuse and release it as a unit. What tips
the balance is whether others depend on the module through versioned
releases.
Rule. Keep the module dependency graph free of cycles. A cycle
makes its modules one module in practice: none can be built, tested
or released without the others. Break it by moving what both sides
need into a module of its own, by an interface the depending module
owns and the other implements, as
inverting dependencies
rule 1 asks, or by an event the depended-on module publishes, as
publishing domain events
describes.
Default. Make a module that many others depend on abstract in
proportion to how many depend on it: it holds the interfaces and
values the others use, while the implementations that change live in
modules that depend on it. Read the counts and the direction of
stability in
diagnosing coupling, rules 9
and 10.
The exception is a stable module of concrete values that rarely
change, such as dates, times and money: it may stay concrete.
Rule. Give each module a small public interface and keep the rest
internal: other modules use only what it publishes, never its
internal classes or its tables, and a check in the build fails on a
dependency the module does not allow. A boundary that only a
convention guards wears away under the first deadline.
Judgement. Build a modular monolith first: modules with their own
public interfaces and their own data inside one deployable unit.
Split a module into a separate service only when it must be
deployed, scaled or owned apart. What tips the balance is whether
that need outweighs the cost of calls across a network, of data no
longer changed in one transaction, and of running another service.
Pattern
Before, LeaveRequests in the staff module asks scheduling's
Appointments port whether a clinician is free, and SlotOpener in
the scheduling module asks staff's Rota whether the clinician is on
duty. Each module's field types name a type in the other, so the two
depend on each other.
Appointments.forClinicianOn(clinician, date) is the query
designing repositories gives
its store, and Slot.startingAt is the notation's factory.
Before:
-- module staff
class LeaveRequests
- appointments: Appointments
+ new(appointments: Appointments)
+ canTakeLeave(clinician: ClinicianId, date: Date): Boolean
return appointments.forClinicianOn(clinician, date).isEmpty()
class Rota
+ isOnDuty(clinician: ClinicianId, startsAt: DateTime): Boolean
-- module scheduling
class SlotOpener
- rota: Rota
+ new(rota: Rota)
+ open(clinician: ClinicianId, startsAt: DateTime): Slot
raises ClinicianOffDuty
if rota.isOnDuty(clinician, startsAt) then
return Slot.startingAt(clinician, startsAt)
else
raise ClinicianOffDuty
The field types create two module dependencies: staff depends on
scheduling through Appointments, and scheduling depends on staff
through Rota. isEmpty() is taken to be true when the list holds no
item, Boolean is the yes-or-no type, and the fences change and store
nothing. Each canTakeLeave sends one query; in the Before it is
forClinicianOn.
After, the staff module declares FreeDays and depends on nothing in
scheduling. Scheduling's AppointmentFreeDays implements that
interface over its own Appointments port, so scheduling depends on
staff, and the composition root hands LeaveRequests an
AppointmentFreeDays.
After:
-- module staff
interface FreeDays
+ isFreeOn(clinician: ClinicianId, date: Date): Boolean
class LeaveRequests
- freeDays: FreeDays
+ new(freeDays: FreeDays)
+ canTakeLeave(clinician: ClinicianId, date: Date): Boolean
return freeDays.isFreeOn(clinician, date)
class Rota
+ isOnDuty(clinician: ClinicianId, startsAt: DateTime): Boolean
-- module scheduling
class AppointmentFreeDays implements FreeDays
- appointments: Appointments
+ new(appointments: Appointments)
+ isFreeOn(clinician: ClinicianId, date: Date): Boolean
return appointments.forClinicianOn(clinician, date).isEmpty()
class SlotOpener
- rota: Rota
+ new(rota: Rota)
+ open(clinician: ClinicianId, startsAt: DateTime): Slot
raises ClinicianOffDuty
if rota.isOnDuty(clinician, startsAt) then
return Slot.startingAt(clinician, startsAt)
else
raise ClinicianOffDuty
The field types create one module dependency: scheduling depends on
staff through FreeDays, and staff names nothing in scheduling. Each
canTakeLeave still sends one query; in the After it is isFreeOn,
which sends forClinicianOn once. Rota and SlotOpener are
unchanged, so the cycle is broken by the interface and the class that
implements it.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- Top-level folders named for technical kinds, such as controllers,
services and repositories, in an application with several business
areas.
- Two modules that import each other, directly or through a third.
- A module that most others depend on and that changes in most
releases.
- A class in one module that uses another module's internal class or
table.
- A module boundary that no build check enforces.
- A plan to split into services in order to fix a dependency tangle.
Common mistakes
- Splitting into separate services before the modules have clean
boundaries inside one deployable unit.
- Breaking a cycle by merging the two modules into one large module.
- A shared module that collects whatever two other modules both need.
- Grouping classes by what they are, such as all entities together,
rather than by what changes together.
- Publishing a whole module because one of its classes is needed
elsewhere.
Related skills
Further reading
- Grouping classes
- Cycles and stability
1---2name: oo-organising-modules3description: Use when grouping classes into packages, when packages depend on each other in a cycle, or choosing between a modular monolith and services.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-organising-modules7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Organising Modules1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920A module is a group of classes with one public interface; a package or21a folder is how the code spells it. How a codebase is divided into22modules decides how much of it one change touches, what can be built23and tested apart, and how many teams must agree before a release. This24skill groups classes by business capability, keeps the dependencies25between modules free of cycles, makes a module that many others depend26on abstract, gives every module a small public interface the build27enforces, and keeps one deployable unit until a module must live apart.28Scheduling, billing and clinical records are capabilities of the29clinic, and the layers of each sit inside its module.3031## When to use3233- You are deciding how to group classes into packages or folders.34- Two modules import each other, directly or through a third.35- A module many others depend on changes in most releases.36- One module uses a class or a table that belongs to another.37- You are choosing between one deployable unit and separate services.38- The build has no check on which module may depend on which.3940## When not to use4142- The question is how tightly two parts are tied, or how to measure43 it: that is44 [diagnosing coupling](../oo-diagnosing-coupling/SKILL.md).45- The question is the layers inside one module and which way they46 depend: that is47 [layering the system](../oo-layering-the-system/SKILL.md).48- The question is where one team's model ends and another's begins:49 that is50 [bounding contexts](../oo-bounding-contexts/SKILL.md).51- The code is one small module with one capability and one team.52 Leave it as it is.5354## Core rules55561. Default. **Make the top-level modules business capabilities, such as57 scheduling, billing and clinical records, not technical kinds such58 as controllers, services and repositories.** The layers of each59 capability then sit inside its module, so a change to one capability60 touches one module.6162 The exception is a small application with one capability, where one63 module with a folder per layer is enough.64652. Rule. **Put classes that change for the same reason and are used66 together in one module, and keep apart classes that are not used67 together.** A module that bundles unrelated classes makes every user68 depend on, rebuild and retest all of them for a change to one. A69 capability spread over several modules makes one change touch them70 all.71723. Judgement. **Weigh three pulls on a module's contents: classes that73 change together, classes that are used together, and classes74 released together under one version for others to reuse.** Early in75 a project, group for change. Once other teams reuse a module through76 its releases, group for reuse and release it as a unit. What tips77 the balance is whether others depend on the module through versioned78 releases.79804. Rule. **Keep the module dependency graph free of cycles.** A cycle81 makes its modules one module in practice: none can be built, tested82 or released without the others. Break it by moving what both sides83 need into a module of its own, by an interface the depending module84 owns and the other implements, as85 [inverting dependencies](../oo-inverting-dependencies/SKILL.md)86 rule 1 asks, or by an event the depended-on module publishes, as87 [publishing domain events](../oo-publishing-domain-events/SKILL.md)88 describes.89905. Default. **Make a module that many others depend on abstract in91 proportion to how many depend on it: it holds the interfaces and92 values the others use, while the implementations that change live in93 modules that depend on it.** Read the counts and the direction of94 stability in95 [diagnosing coupling](../oo-diagnosing-coupling/SKILL.md), rules 996 and 10.9798 The exception is a stable module of concrete values that rarely99 change, such as dates, times and money: it may stay concrete.1001016. Rule. **Give each module a small public interface and keep the rest102 internal: other modules use only what it publishes, never its103 internal classes or its tables, and a check in the build fails on a104 dependency the module does not allow.** A boundary that only a105 convention guards wears away under the first deadline.1061077. Judgement. **Build a modular monolith first: modules with their own108 public interfaces and their own data inside one deployable unit.109 Split a module into a separate service only when it must be110 deployed, scaled or owned apart.** What tips the balance is whether111 that need outweighs the cost of calls across a network, of data no112 longer changed in one transaction, and of running another service.113114## Pattern115116Before, `LeaveRequests` in the staff module asks scheduling's117`Appointments` port whether a clinician is free, and `SlotOpener` in118the scheduling module asks staff's `Rota` whether the clinician is on119duty. Each module's field types name a type in the other, so the two120depend on each other.121`Appointments.forClinicianOn(clinician, date)` is the query122[designing repositories](../oo-designing-repositories/SKILL.md) gives123its store, and `Slot.startingAt` is the notation's factory.124125Before:126127```text128-- module staff129class LeaveRequests130 - appointments: Appointments131 + new(appointments: Appointments)132 + canTakeLeave(clinician: ClinicianId, date: Date): Boolean133 return appointments.forClinicianOn(clinician, date).isEmpty()134135class Rota136 + isOnDuty(clinician: ClinicianId, startsAt: DateTime): Boolean137138-- module scheduling139class SlotOpener140 - rota: Rota141 + new(rota: Rota)142 + open(clinician: ClinicianId, startsAt: DateTime): Slot143 raises ClinicianOffDuty144 if rota.isOnDuty(clinician, startsAt) then145 return Slot.startingAt(clinician, startsAt)146 else147 raise ClinicianOffDuty148```149150The field types create two module dependencies: staff depends on151scheduling through `Appointments`, and scheduling depends on staff152through `Rota`. `isEmpty()` is taken to be true when the list holds no153item, `Boolean` is the yes-or-no type, and the fences change and store154nothing. Each `canTakeLeave` sends one query; in the Before it is155`forClinicianOn`.156157After, the staff module declares `FreeDays` and depends on nothing in158scheduling. Scheduling's `AppointmentFreeDays` implements that159interface over its own `Appointments` port, so scheduling depends on160staff, and the composition root hands `LeaveRequests` an161`AppointmentFreeDays`.162163After:164165```text166-- module staff167interface FreeDays168 + isFreeOn(clinician: ClinicianId, date: Date): Boolean169170class LeaveRequests171 - freeDays: FreeDays172 + new(freeDays: FreeDays)173 + canTakeLeave(clinician: ClinicianId, date: Date): Boolean174 return freeDays.isFreeOn(clinician, date)175176class Rota177 + isOnDuty(clinician: ClinicianId, startsAt: DateTime): Boolean178179-- module scheduling180class AppointmentFreeDays implements FreeDays181 - appointments: Appointments182 + new(appointments: Appointments)183 + isFreeOn(clinician: ClinicianId, date: Date): Boolean184 return appointments.forClinicianOn(clinician, date).isEmpty()185186class SlotOpener187 - rota: Rota188 + new(rota: Rota)189 + open(clinician: ClinicianId, startsAt: DateTime): Slot190 raises ClinicianOffDuty191 if rota.isOnDuty(clinician, startsAt) then192 return Slot.startingAt(clinician, startsAt)193 else194 raise ClinicianOffDuty195```196197The field types create one module dependency: scheduling depends on198staff through `FreeDays`, and staff names nothing in scheduling. Each199`canTakeLeave` still sends one query; in the After it is `isFreeOn`,200which sends `forClinicianOn` once. `Rota` and `SlotOpener` are201unchanged, so the cycle is broken by the interface and the class that202implements it.203204## Red flags205206Places to look, not verdicts. A red flag becomes a finding only with207evidence: a measurement, a reproducible bug, or a failing test.208209- Top-level folders named for technical kinds, such as controllers,210 services and repositories, in an application with several business211 areas.212- Two modules that import each other, directly or through a third.213- A module that most others depend on and that changes in most214 releases.215- A class in one module that uses another module's internal class or216 table.217- A module boundary that no build check enforces.218- A plan to split into services in order to fix a dependency tangle.219220## Common mistakes221222- Splitting into separate services before the modules have clean223 boundaries inside one deployable unit.224- Breaking a cycle by merging the two modules into one large module.225- A shared module that collects whatever two other modules both need.226- Grouping classes by what they are, such as all entities together,227 rather than by what changes together.228- Publishing a whole module because one of its classes is needed229 elsewhere.230231## Related skills232233- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule234 labels.235- [oo-diagnosing-coupling](../oo-diagnosing-coupling/SKILL.md) measures236 how many modules depend on a module and how unstable it is.237- [oo-hiding-implementation](../oo-hiding-implementation/SKILL.md)238 keeps a module's decisions behind a small interface.239- [oo-inverting-dependencies](../oo-inverting-dependencies/SKILL.md)240 puts an interface in the module that sends it and the implementation241 in the module that answers.242- [oo-publishing-domain-events](../oo-publishing-domain-events/SKILL.md)243 publishes a change for another module to react to.244- [oo-layering-the-system](../oo-layering-the-system/SKILL.md) decides245 the layers inside a module and which way they depend.246- [oo-bounding-contexts](../oo-bounding-contexts/SKILL.md) draws where247 one team's model ends; one context may hold several modules.248249## Further reading250251- [Grouping classes](references/grouping-classes.md)252- [Cycles and stability](references/cycles-and-stability.md)