Item 68: Adhere to generally accepted naming conventions

68. Follow naming conventions

Naming convention

Java's naming convention is well organized in JLS 6.1. Roughly speaking, naming conventions can be divided into typographical and grammatical.

typographical

Package name, module name

Package names and module names are expressed hierarchically by components separated by periods. Components are represented by lowercase letters (and rarely numbers). For packages used outside your organization, start with your organization's Internet domain name upside down (such as com.google). This rule is out of scope for standard packages starting with java and javax. Users must not create packages or modules that start with java or javax. Detailed rules for prefixing Internet domain names to packages are in JLS 6.1.

The rest of the package name consists of one or more component names. Component names are generally recommended to be short strings of up to 8 characters (such as abbreviations).

Class name, interface name

Class names including enumeration types and annotation types, and interface name names consist of words with the first letter of each word capitalized. Except for acronyms and common abbreviations such as max and min, the use of abbreviations should be avoided. Regarding acronyms, it is controversial whether to write them in all capital letters or to capitalize only the first letter, but from the viewpoint of readability, I would like to recommend the method of capitalizing the first letter here.

Method name, field name

Method names and field names are basically the same as the rules for class names and interface names, except that the first letter is lowercase. The only exception to this rule is that constant fields should separate uppercase words with underscores. (NEGATIVE_INFINITY)

Local variables

The naming convention for local variables is similar to that for field variables, but local variables are allowed to name abbreviations in context (i, denom, houseNum, etc.). Variables that are arguments will be integrated into the method documentation, so you need to name them carefully.

Type parameters

Type parameters are basically composed of one character. T is an arbitrary type, E is the element type of the collection, K and V are the key and value types of the map, X is the exception type, and R is the return type. The order when using multiple arbitrary types is T, U, V or T1, T2, T3.

grammatical Grammatic rules for naming are more flexible and controversial than notation rules.

Package name, module name

There is no grammatical naming convention for packages.

Class name, interface name

Classes that can be instantiated, including enums, are named with singular nouns, noun phrases (Thread, PriorityQueue, ChessPiece, etc.). Classes that are not instantiated are often named in the plural of nouns (Collectors, Collections, etc.). An interface may have the same naming convention as a class (Collection, Comparator, etc.) or an adjective ending (Runnable, Iterable, Accessible, etc.). The annotation type has various uses, so it does not apply to any of the above. Nouns, verbs, prepositions and adjectives are all commonly used (BindingAnnotation, Inject, ImplementedBy, Singleton, etc.).

Method name

Methods that perform some action are generally named with a verb or verb phrase (append, drawImage, etc.). Methods that return a boolean are named starting with is or has, followed by words that act as nouns, noun phrases, or adjectives (such as isDigit, isProbablePrime, isEmpty, isEnabled, hasSiblings). Methods that return values other than boolean and methods that return object attributes are named with nouns, noun phrases, and verb phrases that begin with get. Some say that only verb phrases that start with get are allowed, but the grounds are scarce. Readability is usually improved by using noun and noun phrase naming methods.

if (car.speed() > 2 * SPEED_LIMIT)
    generateAudibleAlert("Watch out for cops!");

Some method naming conventions require special mention. Methods that convert the instance type and return it as an independent object are sometimes called toType methods (toString, toArray, etc.). Methods that return an object of a different type than the received object are sometimes called asType methods (such as asList). A method that returns a primitive value with the same value as the called object is sometimes called a typeValue method (such as intValue). Common names for factory methods include include from, of, valueOf, instance, getInstance, newInstance, getType, newType, etc. (Item1).

Field name, local variable

The grammar rules for field names are less important. That's because a well-designed API has few exposed fields. For boolean type fields, the one in which only the first character string of the accessor method disappears is often adopted (initialized, composite, etc.). In other fields, it is often a noun or noun phrase (height, digits, bodyStyle). The grammar rules for local variables are much looser than fields.

Recommended Posts

Item 68: Adhere to generally accepted naming conventions
Item 39: Prefer annotations to naming patterns
Java basic naming conventions