Modules and packages: namespaces that scale teams

Packages are social; modules are structural

Packages organize source files, control package-private access, and give humans a way to group related types. Modules (introduced in Java 9) take the next step: a compile-time and runtime declaration of what a unit of code requires from the world and what it exports back.

module com.acme.billing {
    requires transitive com.acme.core;
    requires java.net.http;

    exports com.acme.billing.api;          // public API
    // everything else (com.acme.billing.internal) stays hidden
}

Discipline even without modules

Many projects still live on the classpath. The discipline modules enforce is valuable anyway: separate a thin public API package from a rich internal package, and resist the urge to reach across module boundaries just because the classpath allows it.