Take Care of Your Module Declarations

Nicolai Parlog
Aug 21 · 3 min read

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:

  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, any time 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.

97 Things

Tap into the wisdom of experts to learn what every great practitioner should know, no matter what technology or techniques you use. With the 97 short and extremely useful tips, you’ll expand your skills by adopting new approaches while learning best practices.

Nicolai Parlog

Written by

Developer (mostly Java), blogger (http://codefx.org/), author (http://tiny.cc/jms), trainer (http://courses.codefx.org & https://www.youtube.com/c/codefx)

97 Things

97 Things

Tap into the wisdom of experts to learn what every great practitioner should know, no matter what technology or techniques you use. With the 97 short and extremely useful tips, you’ll expand your skills by adopting new approaches while learning best practices.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade