Many codebases use a naming convention — an internal sub-package, which Go formalizes as a compiler-enforced rule for any package under a directory literally named internal/, or an impl/internal suffix — to mark implementation packages that outside code shouldn't import. In a language like Java or Kotlin, where the compiler does NOT understand this convention the way Go's does, why do teams still use it, and what has to back it up for the boundary to actually hold?

## Compiler-enforced in Go, convention on the JVM Go's toolchain gives special, compiler-enforced meaning to any directory literally named `internal`: a package under `.../internal/...` can only be imported by code that lives in the directory tree rooted at the parent of that internal directory — go build/go vet refuse to compile an import that reaches into someone else's `internal/` tree from outside it, no matter how "public" the identifiers inside look by Go's exported-name capitalization convention. **Java and Kotlin have no equivalent language rule.** A package or folder named `internal`, `impl`, or `_private` is pure convention — the javac/kotlinc compilers attach zero special meaning to that string, so a public class inside a folder called `internal` is exactly as importable from anywhere as a public class inside a folder called `api`. ## Why teams still use it Despite the lack of enforcement, the naming convention persists because it's cheap and high-leverage as a **signal**: a developer opening the codebase, an IDE's autocomplete list, or a reviewer scanning a diff immediately understands "don't import from here" the moment they see `internal` or `impl` in the package path, even before reading any documentation. It costs nothing to adopt and works across language boundaries and tools that don't understand deeper visibility mechanisms. It's also often the only option available for classes that structurally must be public for a framework to work: - JPA entities - Spring `@Component`/`@Service` beans - Jackson-serialized DTOs These frequently can't be package-private/internal because the framework needs to instantiate or proxy them across package/module lines — so the convention becomes the fallback boundary marker precisely where visibility modifiers run out. ## What has to back it up For the convention to survive contact with a growing team and deadline pressure, it needs an **automated enforcer**, because "everyone knows not to import internal packages" degrades exactly like any unenforced rule: it holds during code review by people who remember it, and fails the first time someone new, in a hurry, or unaware of the convention just imports the class because it compiles fine and does what they need. The standard backstop on the JVM is an **architecture test**: - ArchUnit rules such as `noClasses().that().resideOutsideOfPackage("..internal..").should().dependOnClassesThat().resideInAPackage("..internal..")`; - or, for module-level internal boundaries specifically, Spring Modulith's `ApplicationModules.verify()`, which understands that each module's internal sub-package shouldn't be reached from outside that module. These run as ordinary tests in CI, so a violation fails the build at the commit that introduced it, giving the "internal" folder name real teeth it doesn't get from the compiler alone. ## Convention against enforcement | Approach | What it buys | What it costs | |---|---|---| | Convention-only enforcement | essentially free to adopt | fragile over time and team size — it relies entirely on cultural memory and diligent code review, both of which degrade under turnover, growth, and deadline pressure, and neither shows up as a build failure when violated | | Enforced-by-test boundaries | far more durable — a violation cannot merge without either fixing the import or deliberately changing the rule | ongoing maintenance: rules must be kept in sync as the package structure evolves, false positives can block real work until fixed, and teams onboarding the tooling typically need a baseline/freeze mechanism, such as ArchUnit's freeze API, to adopt the rule against a legacy codebase without an immediate flood of failures | ## The erosion when nothing checks The characteristic failure mode without an automated backstop is slow erosion into a **de facto public API**: a developer under deadline pressure imports directly from `payment.internal.RefundCalculator` because it does exactly what they need and nothing stops them; other teams copy that pattern over the following year because "it's already done that way elsewhere"; by the time someone tries to refactor RefundCalculator's signature, half the codebase breaks, and the internal naming has become purely decorative. ## Where it shows up — a Spring Modulith backend A concrete real-world instance of the enforced version: a Spring Modulith backend where each top-level module keeps its implementation classes in an internal sub-package and exposes only a single `*Api` interface at the module root. `ApplicationModules.verify()`, run as part of the standard test suite, walks the compiled module graph and fails the build the moment any module's code imports a class from another module's internal package, turning what would otherwise be a naming convention into an actively-checked architectural contract every commit has to satisfy.