CHAPTER 6: Names

Previous

Java Language

Index

Next

6.8 Naming Conventions

The Java system and standard classes attempt to use, whenever possible, names chosen according to the conventions presented here. These conventions help to make code more readable and avoid certain kinds of name conflicts.

We recommend these conventions for use in all Java programs. However, these conventions should not be followed slavishly if long-held conventional usage dictates otherwise. So, for example, the sin and cos methods of the class java.lang.Math have mathematically conventional names, even though these method names flout Java convention because they are short and are not verbs.

6.8.1 Package Names

Names of packages that are to be made widely available should be formed as described in S7.7. Such names are always qualified names whose first identifier consists of two or three uppercase letters that name an Internet domain, such as COM , EDU , GOV , MIL , NET , ORG , or a two-letter ISO country code such as UK or JP . Here are examples of hypothetical unique names that might be formed under this convention:

COM.JavaSoft.jag.Oak
ORG.NPR.pledge.driver
UK.ac.city.rugby.game

Names of packages intended only for local use should have a first identifier that begins with a lowercase letter, but that first identifier specifically should not be the identifier java ; package names that start with the identifier java are reserved to JavaSoft for naming standard Java packages.

When package names occur in expressions:

• If a package name is hidden by a field declaration, then import declarations (S7.5) can usually be used to make available the type names declared in that package.
• If a package name is hidden by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other Java code.
• The first component of a package name is normally not easily mistaken for a type name, as a type name normally begins with a single uppercase letter. (The Java language does not actually rely on case distinctions to determine whether a name is a package name or a type name. It is not possible for a type name to hide a package name.)

6.8.2 Class and Interface Type Names

Names of class types should be descriptive nouns or noun phrases, not overly long, in mixed case with the first letter of each word capitalized. For example:

ClassLoader
SecurityManager
Thread
Dictionary
BufferedInputStream

Likewise, names of interface types should be short and descriptive, not overly long, in mixed case with the first letter of each word capitalized. The name may be a descriptive noun or noun phrase, which is appropriate when an interface is used as if it were an abstract superclass, such as interfaces java.io.DataInput and java.io.DataOutput ; or it may be an adjective describing a behavior, as for the interfaces java.lang.Runnable and java.lang.Cloneable .

Hiding involving class and interface type names is rare. Names of fields, parameters, and local variables normally do not hide type names because they conventionally begin with a lowercase letter whereas type names conventionally begin with an uppercase letter.

6.8.3 Method Names

Method names should be verbs or verb phrases, in mixed case, with the first letter lowercase and the first letter of any subsequent words capitalized. Here are some additional specific conventions for method names:

• Methods to get and set an attribute that might be thought of as a variable V should be named get V and set V. An example is the methods getPriority (S20.20.22) and setPriority (S20.20.23) of class java.lang.Thread .
• A method that returns the length of something should be named length , as in class java.lang.String (S20.12.11).
• A method that tests a boolean condition V about an object should be named is V. An example is the method isInterrupted of class java.lang.Thread (S20.20.32).
• A method that converts its object to a particular format F should be named to F. Examples are the method toString of class java.lang.Object (S20.1.2) and the methods toLocaleString (S21.3.27) and toGMTString (S21.3.28) of class java.util.Date .

Whenever possible and appropriate, basing the names of methods in a new class on names in an existing class that is similar, especially a class from the standard Java Application Programming Interface classes, will make it easier to use.

Method names cannot hide or be hidden by other names (S6.5.6).

6.8.4 Field Names

Names of fields that are not final should be in mixed case with a lowercase first letter and the first letters of subsequent words capitalized. Note that well-designed Java classes have very few public or protected fields, except for fields that are constants (final static fields) (S6.8.5).

Fields should have names that are nouns, noun phrases, or abbreviations for nouns. Examples of this convention are the fields buf , pos , and count of the class java.io.ByteArrayInputStream (S22.6) and the field bytesTransferred of the class java.io.InterruptedIOException (S22.30.1).

Hiding involving field names is rare.

• If a field name hides a package name, then an import declaration (S7.5) can usually be used to make available the type names declared in that package.
• If a field name hides a type name, then a fully qualified name for the type can be used.
• Field names cannot hide method names.
• If a field name is hidden by a declaration of a parameter or local variable, then the name of the parameter or local variable can be changed without affecting other Java code.

6.8.5 Constant Names

The names of constants in interface types should be, and final variables of class types may conventionally be, a sequence of one or more words, acronyms, or abbreviations, all uppercase, with components separated by underscore "_ " characters. Constant names should be descriptive and not unnecessarily abbreviated. Conventionally they may be any appropriate part of speech. Examples of names for constants include MIN_VALUE , MAX_VALUE , MIN_RADIX , and MAX_RADIX of the class java.lang.Character .

A group of constants that represent alternative values of a set, or, less frequently, masking bits in an integer value, are sometimes usefully specified with a common acronym as a name prefix, as in:

interface ProcessStates {
	int PS_RUNNING = 0;
	int PS_SUSPENDED = 1;
}

Hiding involving constant names is rare:

• Constant names should be longer than three letters, so that they do not hide the initial component of a unique package name.
• Constant names normally have no lowercase letters, so they will not normally hide names of packages, types, or fields, whose names normally contain at least one lowercase letter.
• Constant names cannot hide method names, because they are distinguished syntactically.

6.8.6 Local Variable and Parameter Names

Local variable and parameter names should be short, yet meaningful. They are often short sequences of lowercase letters that are not words. For example:

• Acronyms, that is the first letter of a series of words, as in cp for a variable holding a reference to a ColoredPoint
• Abbreviations, as in buf holding a pointer to a buffer of some kind
• Mnemonic terms, organized in some way to aid memory and understanding, typically by using a set of local variables with conventional names patterned after the names of parameters to widely used classes. For example:
  • in and out , whenever some kind of input and output are involved, patterned after the fields of java.lang.System
  • off and len , whenever an offset and length are involved, patterned after the parameters to the read and write methods of the interfaces DataInput and DataOutput of java.io

One-character local variable or parameter names should be avoided, except for temporary and looping variables, or where a variable holds an undistinguished value of a type. Conventional one-character names are:

• b for a byte
• c for a char
• d for a double
• e for an Exception
• f for a float
• i , j , and k for integers
• l for a long
• o for an Object
• s for a String
• v for an arbitrary value of some type

Local variable or parameter names that consist of only two or three uppercase letters should be avoided to avoid potential conflicts with the initial country codes and domain names that are the first component of unique package names (S7.7).