Software EngineeringArchive edition6 min read

Designing modules around stable boundaries

Separate responsibilities so changing one part does not disrupt unrelated behavior.

Interlocking modular blocks and structured outlines — Designing modules around stable boundaries
Original ARTware computational illustration.

A small application rarely arrives with a fully formed architecture. Its first version might load a few records, check a field and display the result. The trouble starts when an additional workflow needs the same records, but follows a different path through the original script. The two workflows then share incidental implementation details as well as genuinely shared behavior. Four months later, changing the display format appears to alter the set of records that reach the screen. No individual statement looks particularly confusing. It is the arrangement of responsibilities that makes the system difficult to change.

A module is most useful when it owns an identifiable set of decisions. Merely dividing a long file into many short files does not establish meaningful boundaries. A stable boundary lets another part of the application request an operation without knowing every detail of how it is performed. The boundary should reflect the behavior that is likely to remain meaningful even if the current implementation is replaced. That may be a rule for choosing eligible listings, a calculation of shipping costs or an operation that stores an accepted order.

Start with the decisions, not the directories

Imagine a catalog that contains drafts, published items and archived items. A listing generator reads these records and creates cards for a public website. At first the generator filters its input to include only published items. Later, a separate export utility implements the same rule independently. A third component adds a publication date check, but the other two forget to adopt it. The three outputs begin to disagree. This is a boundary problem: responsibility for determining public visibility has become distributed among components that should merely consume an established decision.

Instead of beginning by creating a different folder hierarchy, write down the rule that all three callers need. Identify what the decision depends on, such as the record's status and the current date. Decide which component should be responsible for evaluating those facts. It might expose an operation that returns visible records or a predicate that answers whether a given record is visible. Each caller then uses the same rule. The module that builds a card can focus on the title, preview image and links, rather than interpreting publication policies itself.

Avoid an interface that merely mirrors the implementation

An interface should express an operation the caller can understand in its own terms. Suppose the catalog stores records in several tables. A renderer needs a title, a preview image and a destination address. Giving it direct access to table connections and intermediate fields forces the renderer to know about storage choices. A narrower catalog operation can assemble these values into a small record. The renderer receives exactly the information it needs to draw the card. If the underlying storage later changes, callers may remain untouched.

A stable interface does not necessarily need a formal language construct called an interface. A clearly named function, a module export or a documented data structure can establish the same agreement. What matters is that callers rely on an explicit shape and meaningful behavior. Define the input, output and failure conditions. If the catalog operation cannot find an item, for example, it should have a clear way to signal that outcome. Letting every caller infer absence from a slightly different set of field values is an invitation to inconsistent behavior.

Related reading: Handling errors in a predictable way.

Choose a direction for dependencies

It is natural for the public listing generator to depend on the catalog module: it needs catalog information in order to generate output. The reverse relationship deserves more scrutiny. If the catalog must load the rendering component merely to decide whether an item can be considered public, the two components become harder to understand separately. They may also become difficult to initialize and test. Start by drawing a simple dependency diagram. A line represents the use of an operation or data contract from another component, not just an import statement.

Look for cycles and unexpected dependencies. A cycle can indicate that two modules own fragments of one decision, or that a function has been placed in a module because it was convenient to reach at the time. There may be a good reason for a connector or orchestrator to reference both sides. For example, an application entry point can retrieve records and pass them to a renderer. This does not require either the renderer or the catalog to own the complete publishing process. The orchestrator expresses the order while the components retain their distinct roles.

Interlocking modular blocks and structured outlines
ARTware visual study. A complementary computational composition.

Separate rules from the circumstances in which they are run

A visibility rule that reads the system clock and performs a database query can be harder to exercise than one operating on known values. That does not mean every dependency must disappear. It means the module needs an explicit distinction between the rule and the environment supplying its inputs. In this example the operation might receive a date and a record whose relevant fields have already been loaded. A surrounding operation can be responsible for obtaining those values in the production application. A test can provide a date and a record directly.

This arrangement makes the behavior easier to examine. Set the date to the day before the scheduled release, then to the release date itself. Decide which outcome the business considers correct. Repeat the exercise with a missing publication date or a withdrawn item. A small set of examples can reveal uncertainty about the rule that a complicated integration test might obscure. The same examples also provide useful documentation of the boundary. Anyone changing eligibility later can see which assumptions have already been made.

Do not mistake quantity for good architecture

Creating a module for every helper can make shared work unnecessarily fragmented. A function that adjusts whitespace in a particular card might belong directly in the renderer, especially when no other component needs it. Introducing a generic formatting service may create a configuration system and a new dependency where a local expression would suffice. Excessive separation forces readers to travel between files just to understand a simple operation. The cost is particularly visible when a small change needs coordinated reviews and version changes across components that never vary independently.

The appropriate size of a module depends on the way work changes. If the publishing rule is shared by a website, a feed and a downloadable inventory, a dedicated module is easier to justify. If two operations always change together because they describe one tightly connected concept, separate modules may not improve anything. Begin with a practical distinction, then refine the shape as evidence accumulates. There is little benefit in trying to predict the exact organization that a project will need several years in advance.

Verify the design with realistic changes

Consider the two changes a catalog team is most likely to make. First, a public record should require a preview image in order to be eligible. Second, the public card should place its headline below the image instead of above it. In a useful design, the first change affects the catalog visibility rule and tests for eligible records. The second affects the rendering component and its layout checks. Some integration verification is appropriate for both, but the developers should not repeatedly edit unrelated decision logic merely to reposition the headline.

Keep an eye on the direction of changes as the application grows. A boundary that an old requirement justified might no longer be useful. More than one module may have begun storing overlapping copies of a fact; alternatively, a seemingly convenient module might now own several unrelated policies. Refactoring becomes appropriate when these patterns actually cause difficulty. A stable boundary is not permanent simply because the name of its file has existed for a long time. It earns its place by making normal changes easier to understand, carry out and verify.

Finally, write down one short description of each significant module's ownership. It can take the form of a few sentences beside the public operations. Explain which decisions belong inside, which dependencies provide input and what callers should avoid assuming. This makes ordinary maintenance a little less dependent on conversations with the original author. When a future feature arrives, developers can use these statements to place the new behavior deliberately instead of allowing convenience to determine the architecture once again.

Explore the implementation area: Backend development.