Maven POM file best practices

Owned by Aaron Hoffer
Last updated: Oct 22, 2019 by Matthew Calcote
2 min read

Author: Vina Martin (Deactivated)

Plugins:

  • Eliminate phase overrides OR be sure to provide proper documentation to explain why this override is necessary
  • Jacoco overrides cause Maven warnings in most/all poms because the version is missing, evaluate a solution for this to clean up Maven warnings
  • Consider moving plugins that may be used across downstream projects to ddf-parent's pluginManagement definition

Dependencies:

  • Eliminate unused, redundant dependencies
  • IntelliJ can help find duplicated dependencies in poms
  • Evaluate dependencies that may have been copy-pasted and are not used
  • Double check embed dependencies and import package
  • Tighten dependency scopes when possible (6 scopes are available: compile, provided, runtime, test, system, import)
  • Try to eliminate hardcoded version numbers when possible
  • Try to eliminate overwritten version numbers OR be sure to provide proper documentation to explain version overrides
  • Evaluate version inconsistencies and eliminate them using properties in the root pom OR dependency management when possible
  • Remove usages of <dependencyManagement> at modules that do not have any sub modules (there is nothing to inherit these dependencies)
  • Instead refactor these sections to simply be <dependencies> for any dependencies in <dependencyManagement> that this module needs
  • Eliminate the anti-pattern of having submodules listed in <dependencyManagement>
  • Refactor poms to explicitly use project.version for submodule dependencies and scope them properly
  • Consider refactoring global dependencies into <dependencyManagement> (This can be difficult with the test dependencies)
  • Consider eliminating dependencies in <dependencyManagement> that have a version property
  • Since these dependencies already have a version property, simply refactor poms that inherit this dependency to explicitly use the version property instead of getting it from dependency management
  • Refactor version properties that are duplicated in multiple submodules to live in the most appropriate parent pom
  • Some submodules redefine the same version properties for their submodules; however, these properties should live in the appropriate parent pom so the versions do not diverge
  • Remove dependency conflicts with dependency management

Style:

  • Consistency in the layout of poms makes poms easy to read at a glance
  • Consider refactoring poms where the dependencies stanza is at the end to have this stanza toward the top (under <packaging>) as it is in most poms in the code base
  • Enforce consistent <name> styling throughout the code base
  • Enforce documenting low/non-existent Jacoco coverage numbers
  • (Going forward) Consider grouping dependencies and use comments to explain how/why they are used (especially for new dependencies and overrides)
  • Always document confusing, weird, or hardcoded versions/dependencies/plugins to make it easier for other developers (ideally, we would not have any of these, though!)