Item 56: Adhere to generally accepted naming conventions

1.  Loosely speaking, naming conventions fall into two categories: typographical and grammatical.

 

2.  Package names should be hierarchical with the components separated by periods. Components should consist of lowercase alphabetic characters and, rarely, digits. The name of any package that will be used outside your organization should begin with your organization’s Internet domain name with the top-level domain first. Users must not create packages whose names begin with java or javax. The remainder of a package name should consist of one or more components describing the package. Components should be short, generally eight or fewer characters. Meaningful abbreviations are encouraged.

 

3.  Class and interface names, including enum and annotation type names, should consist of one or more words, with the first letter of each word capitalized. Abbreviations are to be avoided, except for acronyms and certain common abbreviations. If multiple acronyms occur back-to-back, you can still tell where one word starts and the next word ends when you capitalize only the first letter of the acronyms.

 

4.  Method and field names follow the same typographical conventions as class and interface names, except that the first letter of a method or field name should be lowercase.

 

5.  A constant field is a static final field whose value is immutable, whose names should consist of one or more uppercase words separated by the underscore character.

 

6.  Local variable names have similar typographical naming conventions to member names, except that abbreviations are permitted, as are individual characters and short sequences of characters whose meaning depends on the context in which the local variable occurs.

 

7. Type parameter names usually consist of a single letter. Most commonly it is one of these five: T for an arbitrary type, E for the element type of a collection, K and V for the key and value types of a map, and X for an exception. A sequence of arbitrary types can be T, U, V or T1, T2, T3.

 

8. For quick reference, the following table shows examples of typographical conventions:

 

9.  There are no grammatical naming conventions to speak of for packages. Classes, including enum types, are generally named with a singular noun or noun phrase. Interfaces are named like classes, or with an adjective ending in able or ible.

 

10.  Because annotation types have so many uses, no part of speech predominates. Nouns, verbs, prepositions, and adjectives are all common.

 

11.  Methods that perform some action are generally named with a verb or verb phrase (including object). Methods that return a boolean value usually have names that begin with the word is or, less commonly, has, followed by a noun, noun phrase, or any word or phrase that functions as an adjective. Methods that return a non-boolean function or attribute of the object on which they’re invoked are usually named with a noun, a noun phrase, or a verb phrase beginning with the verb get. The form beginning with get is mandatory if the class containing the method is a Bean, and it’s advisable if you’re considering turning the class into a Bean at a later time. Also, there is strong precedent for this form if the class contains a method to set the same attribute.

 

12.  Methods that convert the type of an object, returning an independent object of a different type, are often called toType.

 

13.  Methods that return a view whose type differs from that of the receiving object are often called asType.

 

14.  Methods that return a primitive with the same value as the object on which they’re invoked are often called typeValue.

 

15.  Common names for static factories are valueOf, of, getInstance, newInstance, getType, and newType.

 

16.  Grammatical conventions for field names are less well established and less important than those for class, interface, and method names, as well-designed APIs contain few if any exposed fields. Fields of type boolean are often named like boolean accessor methods with the initial is omitted. Fields of other types are usually named with nouns or noun phrases.

 

17.  Grammatical conventions for local variables are similar to those for fields, but even weaker.