Keep Module Declarations Clean

Module declarations are code and should be treated as such, so make sure your code style is applied. Beyond that, rather than placing directives randomly, structure your module declarations. Here’s the order the JDK uses:

1. Requires, including static and transitive

2. Exports

3. Exports to

4. Opens

5. Opens to

6. Uses

7. Provides

Whatever you decide, if you have a document defining your code style, record the decision there. If you have your IDE, build tool, or code analyzer check such things for you, even better. Try to bring it up to speed so it can automatically check—or even apply—your chosen style.

Comment Module Declarations

Opinions on code documentation, like Javadoc or inline comments, vary wildly, but whatever your team’s position on comments is, extend it to module declarations. If you like abstractions to have a sentence or two explaining their meaning and importance, add such a Javadoc comment to each module. Even if that’s not your style, most people agree that it’s good to document why a specific decision was made. In a module declaration, that could mean adding an inline comment to:

• An optional dependency to explain why the module might be absent

• A qualified export to explain why it isn’t public API, but is partially accessible

• An open package explaining which frameworks are expected to access it

Module declarations present a new opportunity: never before has it been this easy to document the relationships of your project’s artifacts in code.

Review Module Declarations

Module declarations are the central representation of your modular structure, and examining them should be an integral part of any kind of code review you do. Whether it’s looking over your changes before a commit or before opening a pull request, wrapping up after a pair-programming session, or during a formal code review, anytime you inspect a body of code, pay special attention to module-info.java:

• Are new module dependencies necessary (consider replacement with services) and in line with the project’s architecture?

• Is the code prepared to handle the absence of optional dependencies?

• Are new package exports necessary? Are all public classes in there ready for use? Can you reduce the API surface area?

• Does it make sense that an export is qualified, or is it a cop-out to get access to an API that’s not ready to be public?

• Were changes made that could cause problems for downstream consumers that are not part of the build process?

Investing time into diligently reviewing module descriptors might sound like waste, but I see it as an opportunity: never before has it been this easy to analyze and review the relationships of your project’s artifacts and its structure. And not the photographed whiteboard sketch that was uploaded to your wiki a few years ago; no, the real deal, the actual relationships between your artifacts. Module declarations show the naked reality instead of outdated good intentions.