Package Design Checklist, Naming

1.2.1. Start package names with the company’s official root namespace

Rationale:

Consistency. The long-established Java convention is to generate a unique root package name by reversing the internet domain name of the developing organization. When the organization owns multiple internet domain names, the official domain name is used.

Exceptions:

This rule applies to all new APIs and all major new API versions. It does not apply to published APIs, for which item 1.1.11 takes precedence.

If the package naming is changed (for example as part of product rebranding), a major new API version is released. The old package names are deprecated, but kept for backwards compatibility, satisfying item 1.1.11

1.2.2. Use a stable product or product family name at the second level of the package name

Rationale:

Simplicity and Consistency. Developers like short API package names and ideally you should place API packages directly under the root namespace. However, multiple independent business units or product groups may share the root namespace of larger organizations. It is customary to subdivide the root namespace and give each independent unit full control over their own namespace. When the namespace is organized like this, place the API package directly under the namespace you control.

When nobody is officially in charge of controlling the organization’s root namespace, insert a stable product or product family name between the root namespace and the API package. Don’t use the product’s external marketing name, over which you have no control. Use a generic dictionary term or a widely accepted industry concept which best describes your product.

Talk to your product manager about what product name to use.

Do this:

com.company.archiving
com.company.rm
com.company.wcm
com.company.bpm

Don’t do this:

com.company.artesia
com.company.reddot

Exceptions:

If the API itself is the product, place the API package directly under the root namespace.

1.2.3. Use the name of the API as the final part of the package name

Rationale:

Consistency. Developers scan the end of import statements to see what is being imported and expect API names to appear there, so it is important that API classes are imported from a package clearly identified with the name of the API.

If the API is broken up into several packages as suggested in item 1.1.3, these packages should be named appropriately and placed inside a package bearing the name of the API.

For tips on choosing memorable API names see our naming guidelines.

Do this:

package com.company.product; //OK. API name same as product name

public class ApiClass {};

Do this:

package com.company.product.apiname; //OK

public class ApiClass {};

Do this:

package com.company.product.apiname.apipart; //OK. API name still clear

public class ApiClass {};

Don’t do this:

package com.company; //No API name!

public class ApiClass {};

Don’t do this:

package com.company.apipart; //No API name!

public class ApiClass {};

Don’t do this:

package com.company.product.apiname.detail1.detail2; //Difficult to find and import classes!

public class ApiClass {};

1.2.4. Consider marking implementation-only packages by including “internal” in the package name

Rationale:

<Simplicity, Consistency, Safety, and Evolution. We want to help developers quickly skip implementation packages when searching for APIs. We also want to warn them when trying to import from off-limits implementation packages. We recommend the word “internal” placed either at or just below the level of the API. Using “impl” serves the same purpose, but “internal” sounds better and should be used for consistency.

You can use the refactoring feature of a modern IDE to rename implementation packages in existing code. Import statements will be adjusted in all source files. Changing the name of implementation packages should have no impact on external clients.

Do this:

package com.company.product.api;
package com.company.product.api.internal; //good

Do this:

package com.company.product.api1;
package com.company.product.api2;
package com.company.product.internal; //better

Don’t do this:

package com.company.product.api;
package com.company.product.impl;

Don’t do this:

package com.company.product.api;
package com.company.product.other.stuff;

1.2.5. Avoid composite names

Rationale:

Consistency. Composite package names are hard to read because the Java language specification only allows lowercase characters in package names. While underscores are allowed, they are very rarely used in practice, their usage being inconsistent both with the standard Java library names and with the mixed case naming conventions of the other Java identifiers. We ask you to avoid composite package names entirely. Use a single word whenever possible or a well-chosen abbreviation. Remember that we always use fully qualified package names and there is often enough information to give otherwise ambiguous terms a more precise meaning. Consider also that the fully qualified package name can easily become quite long.

Do this:

com.company.process.designer

Do this:

com.company.bpm.designer

Don’t do this:

com.company.businessprocessmanagement.processdesigner

Don’t do this:

com.company.business_process_management.process_designer

1.2.6. Avoid using the same name for both package and class inside the package

Rationale:

Naming. It is generally not a good idea to give the same name to two different things. It becomes outright confusing when it is not clear what the API is. Is it the whole package or just the class?

Do this:

package com.company.product.scheduler; //OK. Scheduler is a package

public class TaskList {};

Do this:

package com.company.product.timing; 

public class Scheduler {}; //OK. Scheduler is a class

Don’t do this:

package com.company.product.scheduler; 

public class Scheduler {};  // What is a scheduler?

1.2.7. Avoid using “api” in package names

Rationale:

Simplicity and Consistency. Callers import mostly APIs. The consistent use of the word “api” would make it redundant, as shown in the example below. This is why none of the core Java APIs has “api” in its package name. For consistency, we should follow the same convention.

Do this:

//consistent avoidance of the word "api"

import java.sql.*
import javax.naming.*
import javax.jms.*
import com.ibm.websphere.sca.*

Don’t do this:

//consistent, but redundant use of the word "api"

import java.sql.api.*
import javax.naming.api.*
import javax.jms.api.*
import com.ibm.websphere.sca.api.*

Don’t do this:

//inconsistent use of the word "api"

import java.sql.*
import javax.naming.*
import javax.jms.*
import com.ibm.websphere.sca.api.*

1.2.8. Do not use marketing, project, organizational unit or geographic location names

Rationale:

Naming. This is a simple application of the “do not use names which can change or may loose their meaning” rule. It deservers its place here only because such mistakes are very frequent in package names.

Don’t do this:

package com.company.borg;        //Internal R&D project name
package com.company.chicago;     //Team location
package com.company.livelink;    //Brand name (Marketing)

1.2.9. Do not use uppercase characters in package names

Rationale:

Consistency. This is a long-established Java convention.

This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 Canada License.