If you’re creating Java modules, your module declarations (
module-info.java files) are easily your most important source files. Each one represents an entire JAR and governs how it interacts with other JARs, so take good care of your declarations!
Here are a few things to look out for.
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:
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, any time you inspect a body of code, pay special attention to
- 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.