module+ sub-modules vs separate files for internal encapsulation

Question

Encapsulation Strategy for Internal Definitions
When designing a Racket application that requires strict control over internal definitions, the goal is to ensure that private logic remains inaccessible to other components unless explicitly exported via the provide form.
Two documented approaches exist for achieving this boundary: using the module+ form to create sub-modules within a single source file, or utilizing separate file-based modules. While both mechanisms restrict visibility, they differ in how they handle architectural decoupling and interaction with the Racket REPL during development.
The primary constraint is maintaining a clean separation of concerns without introducing unnecessary file system overhead, while avoiding ambiguity during interactive evaluation in the REPL.

module+ allows for rapid grouping of internal logic within one file.
Separate files enforce a harder physical boundary between components.

Which approach is more sustainable for maintaining long-term architectural decoupling? Does the use of module+ introduce specific risks regarding active module context during interactive evaluation compared to separate files?

Tasadduq Burney · Answer

Answer
For long‑term architectural decoupling, placing internal definitions in separate file‑based modules is the more sustainable approach.
Confirmed Facts

Separate file modules create a physical boundary that is independent of the parent module’s namespace; the encapsulation does not rely on any phase level of the parent.
When a parent module is required, only the identifiers it explicitly provides are visible in the REPL; identifiers kept in a separate file that is not provided remain inaccessible.
module+ sub‑modules share the same compilation phase as the parent module. Consequently, any code that can access the parent’s phase (e.g., via DrRacket’s “Run” or a namespace‑require that walks the parent’s namespace) can also reach the sub‑module’s bindings, even if they are not provided.

Likely Explanation / Risks
Because module+ keeps the sub‑module in the same phase, interactive evaluation can accidentally expose internal definitions:

In the REPL, after (require 'parent.rkt) all provided exports of parent.rkt are visible, but the sub‑module’s private bindings are hidden unless the sub‑module is explicitly required.
However, tools that evaluate the whole file in the top‑level phase (DrRacket’s “Run”, or a manual namespace-require using the parent’s namespace) make the sub‑module behave as if it were separately required, leaking its private definitions.
This leakage is not a problem for the separate‑file approach because each file is a distinct module with its own phase; there is no shared phase that can be walked to reach unprovided symbols.

Steps to Verify Encapsulation (for this case)

Create a file internal.rkt that defines a private function helper inside a module+ sub‑module and provides only a public API.
Start a Racket REPL and run (require 'internal.rkt).
Attempt to call helper; it should fail if encapsulation works.
Repeat the same test with helper placed in a separate file helper.rkt that is not provided; after requiring the parent, the call must still fail.
To check the REPL risk specific to module+, evaluate (namespace-require (module->namespace (variable-reference->empty-internal-definition 'helper))) after the parent is required. If the call succeeds, the sub‑module’s bindings are reachable via the parent’s namespace, indicating a potential leakage path.

module+ sub-modules vs separate files for internal encapsulation

Encapsulation Strategy for Internal Definitions

1 answer

Answer

Confirmed Facts

Likely Explanation / Risks

Steps to Verify Encapsulation (for this case)

Your perspective belongs here.

0 question comments