Google Best Practices for Java Libraries

Google Best Practices for Java Libraries are rules that minimize problems for consumers of interconnected Java libraries. These practices come from decades of aggregated experience in maintaining open source Java libraries and are informed by many hard-learned lessons from mistakes that have been made. We have found that following these rules results in higher quality Java libraries with fewer dependency conflicts and other kinds of problems. The list is open-ended, so new ones may be added from time to time.

Best practices

• JLBP-1: Minimize dependencies
• JLBP-2: Minimize API surface
• JLBP-3: Use Semantic Versioning
• JLBP-4: Avoid dependencies on unstable libraries and features
• JLBP-5: Do not include a class in more than one classpath entry
• JLBP-6: Rename artifacts and packages together
• JLBP-7: Make breaking transitions easy
• JLBP-8: Advance widely used functionality to a stable version
• JLBP-9: Support the minimum Java version of your consumers
• JLBP-10: Maintain API stability as long as needed for consumers
• JLBP-11: Keep dependencies up to date
• JLBP-12: Make level of support and API stability clear
• JLBP-13: Remove references to deprecated features in dependencies at the first opportunity
• JLBP-14: Specify a single, overridable version of each dependency
• JLBP-15: Publish a BOM for multi-module projects
• JLBP-16: Ensure upper version alignment of dependencies for consumers
• JLBP-17: Coordinate rollout of breaking changes
• JLBP-18: Only shade dependencies as a last resort
• JLBP-19: Place each package in only one module
• JLBP-20: Give each JAR file a module name
• JLBP-21: Upload artifacts to Maven Central
• JLBP-22: Declare all direct dependencies

  Concepts

• What is a diamond dependency conflict?
• Why doesn’t the compiler catch diamond dependency conflicts?
• How does version resolution work in Maven and Gradle?

  Reference

• Glossary: Terms used in the best practices and other places in cloud-opensource-java.