Java Multi-Word Package Naming: JLS Rules & Best Practices

When naming Java packages with multiple words, the standard approach is concatenation without separators. For example: com.company.deepspace, org.apache.commons.collections, or com.example.usermanagement.

While this may seem to reduce readability, it maintains consistency with Java's fundamental design principle that package names must be all lowercase to avoid conflicts with class names.

Java Language Specification (JLS) Rules

The JLS establishes these mandatory requirements for all package names:

Lowercase only: "Package names are written in all lower case to avoid conflict with the names of classes or interfaces"
Valid Java identifiers: Each component must consist of Java letters (A-Z, a-z, underscore, dollar sign) followed by Java letters or digits
Dot separation: Components are separated by dots only
No hyphens or spaces: These characters are forbidden in package names
Reserved word handling: Java keywords require underscore prefixes (e.g., _class, _interface)

⚠️ JLS Violation

Using hyphens, spaces, or mixed case in package names will cause compilation errors. These are not style preferences but language requirements.

Multi-Word Package Strategies

Standard Concatenation

The recommended approach for multi-word packages is direct concatenation without separators:

// Recommended multi-word packages
com.company.deepspace          // deep + space
com.example.usermanagement     // user + management  
org.project.dataaccess         // data + access
com.app.productcatalog         // product + catalog

Domain Name Conversion

When converting domain names with hyphens, Oracle permits underscores:

// Domain conversion examples
hyphenated-name.example.org → org.example.hyphenated_name
my-company.com → com.my_company
api-gateway.service.com → com.service.api_gateway

⚠️ Style Guide Tension

Oracle's underscore allowance for domain conversion creates tension with stricter style guides like Google's, which prohibit underscores entirely.

Industry Approaches

Google's Strict Approach

Google's Java Style Guide is the most restrictive:

"Package names use only lowercase letters and digits (no underscores). Consecutive words are simply concatenated together." — Google Java Style Guide

// Google's approach
com.example.deepspace          // ✅ Correct
com.example.deep_space         // ❌ Forbidden
com.example.deepSpace          // ❌ Forbidden

Real-World Examples

Major projects demonstrate consistent multi-word concatenation:

// Apache projects
org.apache.commons.collections4
org.apache.kafka.clients.consumer

// Spring Framework
org.springframework.boot.autoconfigure
org.springframework.web.servlet

// Jackson
com.fasterxml.jackson.databind
com.fasterxml.jackson.dataformat

Multi-Word Package Examples

✅ Correct Multi-Word Packages

// Business domain packages
com.company.customermanagement
com.company.orderfulfillment
com.company.paymentprocessing
com.company.inventorycontrol

// Technical packages
com.app.databaseaccess
com.app.userinterface
com.app.backgroundservices
com.app.errorhandling

❌ Common Multi-Word Mistakes

// Mixed case violations
com.company.customerManagement    // camelCase forbidden
com.company.OrderFulfillment      // PascalCase forbidden

// Invalid separators
com.company.customer-management   // hyphens forbidden
com.company.customer_management   // underscores discouraged
com.company.customer management   // spaces forbidden

// Overly complex names
com.company.verylongmultiwordpackagenamethatishardtoread

💡 Key Takeaway

While underscores are technically allowed by the JLS for package names, industry practice strongly favors concatenation. Underscores are mainly used for domain name conversion (e.g., hyphenated-domain.com → com.hyphenated_domain) rather than general multi-word packages.

For multi-word Java packages, concatenate words in lowercase without any separators. This approach satisfies JLS requirements and follows industry standards used by major frameworks like Spring, Apache, and Jackson.

Java Multi-Word Package Naming: JLS Rules and Best Practices