Naming Conventions
Introduction
The Java and J2EE naming conventions will ensure that every developer in your team will think the same when he or she needs to create a package, class, methods or variables and more.
Of course we need to make sure that this really happens we'll need an automated way to verify that the naming conventions are followed. In this section (and others) you'll find references to convention rules that can be automatically enforced by tools.
 | Tip
Sun Microsystems has created a naming conventions document for enterprise applications. This document covers all of them plus many others. |
Java Naming
Package Name
Construct your base package name based on the customer's domain name but reversed. The domain name is the main identifying part of a web address (without the 'www' prefix). So for example if the web address of the customer is www.vlaanderen.be then the domain name is vlaanderen.be, so all packages for this customer should start with be.vlaanderen. The project name and sub packages are appended to the reversed domain name.
package be.vlaanderen.myproject.subpackage;
The project name and sub packages follow the reversed domain name.
Classes
Try to keep your class names simple and descriptive. Use whole words, avoid acronyms and abbreviations (unless the abbreviation is much more widely used than the long form, such as URL or HTML).
For example:
public class HelloWorld {
}
public class SocketHandlerThread {
}
 | Note
Many of the code examples in this document will use the class name Foo and the method name bar. |
Interfaces
Interface names should be capitalized like class names. Don't use special prefixes or suffixes to specify interfaces (e.g.: don't use IMyInterface). Treat interface names the same as you do with classes.
For example:
public interface RasterDelegate {
}
Methods
Methods should be verbs, in mixed case with the first letter lowercase, with the first letter of each internal word capitalized. See rule JAN_006: Use A Correct Name For A Method (Enforced) and also the Getter and Setter methods.
For example:
public void run() {
}
public boolean isRunning() {
}
public Color getBackground() {
}
public void setBackground(Color color) {
}
Getters And Setters Methods
The JavaBeans specification defines a standard way in which the properties for a JavaBean instance should be accessed. (The JavaBeans specification can be found at http://java.sun.com/products/javabeans/docs/spec.html)
This same technique can also be applied to regular classes and interfaces to access their attributes.
The methods are divided into accessor and mutator methods:
| Getter (Accessor) |
Get an attribute/property value |
| Setter (Mutator) |
Set an attribute/property value |
The default name for a getter method is getXXX();
and for a setter method setXXX();
Where XXX represents the name of the attribute/property.
The name of a getter/setter method can be different depending on the type of attribute/property it gets or sets.
Boolean properties
Getter: getXXX() OR isXXX() OR hasXXX() OR canXXX()
Setter: setXXX(boolean value)
For example:
boolean enabled;
isEnabled();
setEnabled(true);
Indexed properties
Getter: getXXX(int index)
Setter: setXXX(int index, value)
For example:
ArrayList name = new ArrayList();
name.get(0);
name.set(0, "value");
Variables
Variable names should be short yet meaningful. Non-final variables must start with lower-case characters and the internal words start with capital letters. See rule JAN_004: Use A Correct Name For A Non Final Field (Enforced).
Variable names should not start with underscore {_} or dollar sign $ characters, even though both are allowed. See rule JAN_010: Do Not Use $ In A Name (Enforced).
One-character variable names should be avoided except for temporary throwaway variables. See rule JAN_009: Use A Conventional Variable Name When Possible (Normal).
Common names for temporary variables are:
b for a byte
c for a char
d for a double
e for an Exception
f for a float
i, j or k for an int
l for a long
o for an Object
s for a String
in for an InputStream
out for an OutputStream
Avoid variables names that only differ in case which makes it difficult for the reader to distinguish the variables. See rule JAN_011: Do Not Use Names That Only Differ In Case (High) .
Don't use the Hungarian Notation for any of your variable names.
| Note
In the early days of DOS, Microsoft's Chief Architect Dr. Charles Simonyi introduced an identifier naming convention that adds a prefix to the identifier name to indicate the functional type of the identifier. It came to be known as "Hungarian notation" because the prefixes make the variable names look a bit as though they're written in some non-English language and because Simonyi is originally from Hungary. |
Constants
The names of variables declared as class constants (final and static) should be all uppercase with words separated by under-scores {_}. See rule JAN_005: Use A Correct Name For A Constant (Enforced).
You can define constants on the class or interface that owns them or use one or more separate xxxConstants classes to bundle them.
 | Caution
Before defining something as a constant make sure that it really is a constant and not a configurable property or setting. |
For example declaring constants on a class that owns them:
package be.vlaanderen.examples;
public class ServiceLocator \{
/** The JNDI name of the session EJB */
public static final String JNDI_NAME = "sessionBean";
/** The default J2EE Reference Implementation URL
* If possible move this information to an LDAP storage
* or (if applicable) place it in the J2EE deployment descriptor
* as an environment variable.
*/
public static final String JNDI_URL = "iiop:;
}
For example a xxxConstants class:
package be.vlaanderen.examples;
public final class JNDIConstants {
/** The JNDI name of the session EJB */
public static final String JNDI_NAME = "sessionBean";
/** The default J2EE Reference Implementation URL
* If possible move this information to an LDAP storage
* or (if applicable) place it in the J2EE deployment descriptor
* as an environment variable.
*/
public static final String JNDI_URL = "iiop:;
/**
* Hide constructor, constant classes should never be instantiated
*/
private JNDIConstants() {
}
}
| Note
From JDK 1.5 onwards you'll be able to import your Constant variables through the use of 'static imports'. For example:
import static be.vlaanderen.examples.JNDIConstants.JNDI_NAME;
public class ServiceLocator \{
public Object lookup() throws NamingException \{
return context.lookup(JNDI_NAME);
}
}
|
| In JEE5 you'll no longer use service locators, as shown above, because the object references will get injected using the @Resource annotation based on Inversion Of Control |
Exceptions
The names of Exception classes (classes that extend from java.lang.Exception or java.lang.Throwable) should always end with Exception. See rule JAN_008: Name An Exception Class Ending With Exception (High).
For example:
public class PersonNotFoundException extends Exception \{
}
| Note
Try to be as descriptive as possible when choosing the name of your exception class because often only the name is used to determine the way the exceptional condition should be handled. |
J2EE Naming
Application Name
A J2EE application is delivered in an Enterprise Archive (EAR) file. An EAR file is a standard Java Archive (JAR) file. The Application name must have a .ear extension and written in all-lowercase letters.
For example:
The display name within the deployment descriptor is the application name, written in mixed cases, with a suffix EAR. See rule JEN_013: Use A Correct Name For An Enterprise Application Display Name (High).
For example:
<display-name>MyProjectEAR</display-name>
| Tip
More information on how to develop Java EE applications can be found in the book The J2EE 1.4 Tutorial by Sun Microsystems. |
Web Module Name
Web modules contain JSP files, class files for servlets, GIF and HTML files, and a web deployment descriptor. Web modules are packaged as JAR files and must have a .war (Web ARchive) extension and written in all lower-case letters.
For example:
The display name within the deployment descriptor is the web module name, written in mixed cases, with a suffix WAR. See rule JEN_014: Use A Correct Name For A Web Module Display Name (High).
For example:
<display-name>MyWebProjectWAR</display-name>
Servlet Name
To clearly identify a servlet we'll suffix the servlet class name with Servlet, for example BookStoreServlet. See rule JEN_008: Name A Servlet Like [Name]Servlet (High).
The servlet display name within the deployment descriptor is the servlet class name.
Filter Name
As of version 2.3 of the Servlet API, a standard way to define filters has been specified. The filtering API is defined by the Filter, FilterChain and FilterConfig interfaces in the javax.servlet package. You define a filter by implementing the Filter interface. The name of any filter must have the suffix 'Filter', for example BasicDecodeFilter. See rule JEN_010: Name A Filter Servlet Like [Name]Filter (High).
The filter display name within the deployment descriptor is the filter class name.
Enterprise Java Beans
Because Enterprise Java Beans are composed of multiple parts, it's useful to follow a naming convention for your J2EE applications. The table below summarizes the conventions for the Enterprise Java Beans.
(DD) means that the item is an element in the Enterprise Java Bean's deployment descriptor.
Table 1.2. Naming Conventions For Enterprise Java Beans
| Note
Use of the 'Bean' suffix for the enterprise bean class name can lead to developers thinking they are dealing with a standard JavaBean and not an EJB. Use of the 'EJB' suffice clearly states that the class represents an enterprise Java bean implementation. |
| Note
The Transferable Object (TO) was previously known as Value Object (VO). |
Resource Adapter
Resource adapter modules contain all Java interfaces, classes, native libraries and other documentation, along with the resource adapter deployment descriptor. Together, these implement the Connector architecture for a particular EIS. Resource adapter modules are packaged as JAR files and must have a .rar (Resource adapter ARchive) extension.
Resource Environment References
Resource environment references are logical names associated to different types of administered objects (for example a JMS destination) configured within the deployment descriptor. The developer uses this resource environment reference to lookup and bind to that specific administered object. Below you'll find the naming conventions for the different types of resources.
Enterprise Java Beans
All deployment descriptor references to Enterprise Java Beans must be organized in the ejb subcontext of the application component's environment. See rule JEN_015: Use A Correct Name For An EJB Environment Reference Name (High).
For example:
<ejb-ref>
<description>
This is a reference to the entity bean that
encapsulates access to Foo.
</description>
<ejb-ref-name>ejb/Foo</ejb-ref-name>
<ejb-ref-type>Entity</ejb-ref-type>
<home>be.vlaanderen.FooHome</home>
<remote>be.vlaanderen.Foo</remote>
</ejb-ref>
Java Messaging Service
All deployment descriptor references to Java Messaging Service's must be organized in the jms sub context of the application component's environment. See rule JEN_016: Name A JMS Destination Like [Name]Queue Or [Name]Topic (High).
For example:
<resource-env-ref>
<description>
This is a reference to a JMS queue
</description>
<resource-env-ref-name>jms/FooQueue</resource-env-ref-name>
<resource-env-ref-type>javax.jms.Queue</resource-env-ref-type>
</resource-env-ref>
JDBC
All deployment descriptor references to JDBC related objects must be organized in the jdbc subcontext of the application component's environment. See rule JEN_018: Use A Correct Name For A JDBC Environment Reference Name (High).
For example:
<resource-ref>
<description>
A data source for a Foo database
</description>
<res-ref-name>jdbc/FooDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
<res-auth>Container</res-auth>
<res-sharing-scope>Shareable</res-sharing-scope>
</resource-ref>
The above example uses a database name called FooDB following rule JEN_019: Name A Database Like [Name]DB (High).
