Объявление вводит сущность в программу и включает идентификатор (§3.8), который может быть использован в имени для ссылки на эту сущность.

Объявленная сущность может быть одной из следующих:

Конструкторы (§8.8) также вводятся объявлениями, но используют имя класса, в котором они объявлены, а не вводят новое имя.

Библиотеки классов платформы Java SE стараются использовать, по возможности, имена, выбранные в соответствии с приведенными ниже соглашениями. Эти соглашения помогают сделать код более читаемым и избежать определенных видов конфликтов имен.

Мы рекомендуем использовать эти соглашения во всех программах, написанных на языке программирования Java. Однако не следует следовать этим соглашениям слишком строго, если долго устоявшаяся практика диктует другое. Например, методы sin и cos класса java.lang.Math имеют математически привычные имена, даже если эти имена методов нарушают предлагаемое здесь соглашение, поскольку они короткие и не являются глаголами.

Имена пакетов

Разработчики должны принять меры, чтобы избежать возможности существования двух опубликованных пакетов с одинаковым именем, выбирая уникальные имена пакетов для пакетов, которые широко распространяются. Это позволяет легко и автоматически устанавливать и каталогизировать пакеты. В этом разделе указано рекомендуемое соглашение для создания таких уникальных имен пакетов. Реализации платформы Java SE должны поддерживать автоматическое преобразование набора пакетов из локальных и обычных имен пакетов в уникальный формат имени, описанный здесь.

Если не используются уникальные имена пакетов, могут возникнуть конфликты имен пакетов, не связанных с местом создания одного из конфликтных пакетов. Это может создать ситуацию, которую трудно или невозможно решить пользователю или программисту. Класс ClassLoader может использоваться для изоляции пакетов с одинаковым именем друг от друга в тех случаях, когда пакеты будут иметь ограниченные взаимодействия, но не таким образом, чтобы это было прозрачным для простой программы.

Вы формируете уникальное имя пакета, сначала имея (или принадлежа в организации, которая имеет) имя доменного имени в интернете, например oracle.com. Затем вы инвертируете это имя, компонент за компонентом, чтобы получить, в этом примере, com.oracle, и используете его в качестве префикса для ваших имён пакетов, используя соглашение, разработанное в вашей организации для дальнейшего администрирования имен пакетов. Такое соглашение может определять, что определённые компоненты имени пакета являются названиями подразделения, отдела, проекта, машины или логина.

com.nighthacks.java.jag.scrabble
org.openjdk.tools.compiler
net.jcip.annotations
edu.cmu.cs.bovik.cheese
gov.whitehouse.socks.mousefinder

Первый компонент уникального имени пакета всегда записывается строчными латинскими буквами ASCII и должен быть одним из доменных имен верхнего уровня, таких как com, edu, gov, mil, net или org, или одним из двухбуквенных английских кодов, идентифицирующих страны, как указано в Стандарте ISO 3166.

Имя пакета не должно подразумевать, где пакет хранится в Интернете. Предлагаемое соглашение для создания уникальных имен пакетов просто способ привязать соглашение об именовании пакетов к существующему широко известному регистру уникальных имён, вместо того, чтобы создавать отдельный реестр для имён пакетов.

В некоторых случаях доменное имя может не быть допустимым именем пакета. Вот некоторые рекомендации по работе с такими ситуациями:

Имена пакетов, предназначенные только для локального использования, должны иметь первый идентификатор, начинающийся со строчной буквы, но этот первый идентификатор не должен быть идентификатором java; имена пакетов, начинающиеся с идентификатора java, зарезервированы для пакетов платформы Java SE.

Имена типов классов и интерфейсов

Имена типов классов должны быть описательными существительными или словосочетаниями, не слишком длинными, со смешанным регистром, при этом первая буква каждого слова должна быть заглавной.

ClassLoader
SecurityManager
Thread
Dictionary
BufferedInputStream

Аналогично, имена типов интерфейсов должны быть короткими и описательными, не чрезмерно длинными, с использованием смешанного регистра, где первая буква каждого слова должна быть заглавной. Имя может быть описательным существительным или словосочетанием, что уместно, когда интерфейс используется как абстрактный суперкласс, например, интерфейсы java.io.DataInput и java.io.DataOutput; или это может быть прилагательное, описывающее поведение, как в интерфейсах Runnable и Cloneable.

Имена переменных типа

Имена переменных типа должны быть ёмкими (если возможно, одним символом) и выразительными, и не должны включать строчные буквы. Это облегчает различение параметров типа от обычных классов и интерфейсов.

Типы контейнеров должны использовать имя E для типа их элементов. Карты должны использовать K для типа их ключей и V для типа их значений. Имя X должно использоваться для произвольных типов исключений. Мы используем T для типа, когда нет более специфичных различий в типе. (Это часто встречается в методах с параметрами дженериков).

Если имеется несколько параметров типа, обозначающих произвольные типы, следует использовать буквы, соседствующие с T в алфавите, например, S. В качестве альтернативы допустимо использовать числовые индексы (например, T1, T2) для различения различных переменных типа. В таких случаях все переменные с тем же префиксом должны иметь индексы.

Если метод с дженериками появляется внутри дженерик-класса, рекомендуется избегать использования одинаковых имён для параметров типа метода и класса, чтобы избежать путаницы. То же самое относится к вложенным дженерик-классам.

public class HashSet<E> extends AbstractSet<E> { ... }
public class HashMap<K,V> extends AbstractMap<K,V> { ... }
public class ThreadLocal<T> { ... }
public interface Functor<T, X extends Throwable> {
    T eval() throws X;
}

Когда параметры типа не подходят под одну из упомянутых категорий, имена должны быть выбраны как можно более осмысленными в рамках одного символа. Упомянутые выше имена (E, K, V, X, T) не должны использоваться для параметров типа, которые не попадают в указанные категории.

Имена методов

Имена методов должны быть глаголами или глагольными словосочетаниями, со смешанным регистром, с первой буквой в нижнем регистре и первой буквой каждого последующего слова в верхнем регистре. Ниже приведены дополнительные конкретные соглашения для имён методов:

По возможности и применимости, основание имён методов в новом классе на именах в существующем похожем классе, особенно классе из API платформы Java SE, сделает его использование проще.

Имена полей

Имена полей, которые не являются final, должны быть в смешанном регистре с первой буквой в нижнем регистре и первой буквой последующих слов в верхнем регистре. Обратите внимание, что хорошо спроектированные классы имеют очень мало public или protected полей, за исключением полей, которые являются константами (static final поля).

Поля должны иметь имена, являющиеся существительными, словосочетаниями из существительных или сокращениями существительных.

Имена констант

Имена констант в типах интерфейсов должны быть, а final переменные типов классов могут быть традиционно, последовательностью одного или нескольких слов, аббревиатур или сокращений, полностью заглавными, с компонентами, разделенными символами подчёркивания "_". Имена констант должны быть описательными и не излишне сокращенными. Традиционно они могут быть любой соответствующей частью речи.

Группа констант, представляющих альтернативные значения набора или, реже, маскирующих битов в целочисленном значении, иногда удобно задавать с общим аббревиатурным префиксом в качестве имени.

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

Имена локальных переменных и параметров

Имена локальных переменных и параметров должны быть короткими, но осмысленными. Они часто представляют собой короткие последовательности строчных букв, которые не являются словами, например:

Имена локальных переменных или параметров из одного символа следует избегать, за исключением временных и циклических переменных или когда переменная содержит неопределённое значение типа. Традиционные имена из одного символа:

Имена локальных переменных или параметров, состоящих только из двух или трех строчных букв, не должны конфликтовать с начальными кодами стран и доменными именами, являющимися первой частью уникальных имён пакетов.

Локальная переменная (§14.4), формальный параметр (§8.4.1), параметр исключения (§14.20) и локальный класс (§14.3) могут ссылаться только с использованием простого имени (§6.2), а не с квалифицированным именем (§6.6).

Некоторые объявления запрещены в области действия локальной переменной, формального параметра, параметра исключения или объявления локального класса, потому что невозможно отличить объявленные сущности, используя только простые имена.

Например, если имя формального параметра метода может быть повторно объявлено как имя локальной переменной в теле метода, то локальная переменная будет затемнять формальный параметр, и формальный параметр больше не будет виден — нежелательный результат.

Ошибка компиляции, если имя формального параметра повторно объявляется как локальная переменная метода или конструктора; или как параметр исключения в catch-оператор в try операторе в теле метода или конструктора; или как ресурс в операторе try-с-ресурсами в теле метода или конструктора.

Ошибка компиляции, если имя локальной переменной v повторно объявляется как локальная переменная непосредственно окружающего метода, конструктора или блока инициализации в области действия v; или как параметр исключения в catch-оператор в try-оператор непосредственно окружающего метода, конструктора или блока инициализации в области действия v; или как ресурс в операторе try-с-ресурсами непосредственно окружающего метода, конструктора или блока инициализации в области действия v.

Ошибка компиляции, если имя локального класса C повторно объявляется как локальный класс непосредственно окружающего метода, конструктора или блока инициализации в области действия C.

Ошибка компиляции, если имя параметра исключения повторно объявляется в блоке Блок catch-оператор в качестве локальной переменной непосредственно окружающего метода, конструктора или блока инициализации; или как параметр исключения в catch-оператор в try-оператор непосредственно окружающего метода, конструктора или блока инициализации; или как ресурс в операторе try-с-ресурсами непосредственно окружающего метода, конструктора или блока инициализации.

Ошибка компиляции, если имя переменной, объявленной в ResourceSpecification операторе try-с-ресурсами (§14.20.3), повторно объявляется в блоке try Блок как локальная переменная непосредственно окружающего метода, конструктора или блока инициализации, или как параметр исключения в catch-оператор в try-оператор непосредственно окружающего метода или блока инициализации.

Перевод оператора try-с-ресурсами подразумевает правило выше.

Несмотря на правила против повторного объявления переменных, правила затемнения (§6.4.1) допускают повторное объявление в определенных объявлениях вложенных классов (т.е. локальных классов (§14.3) и анонимных классов (§15.9)) следующим образом:

class Test1 {
    public static void main(String[] args) {
        int i;
        for (int i = 0; i < 10; i++)
            System.out.println(i);
    }
}

class Test2 {
    public static void main(String[] args) {
        int i;
        class Local {
            {
                for (int i = 0; i < 10; i++)
                    System.out.println(i);
            }
        }
        new Local();
    }
}

class Test3 {
    public static void main(String[] args) {
        for (int i = 0; i < 10; i++)
            System.out.print(i + " ");
        for (int i = 10; i > 0; i--)
            System.out.print(i + " ");
        System.out.println();
    }
}

0 1 2 3 4 5 6 7 8 9 10 9 8 7 6 5 4 3 2 1

Значение имени зависит от контекста его использования. Определение значения имени требует трех шагов:

Использование контекста помогает свести к минимуму конфликты имен между сущностями разных типов. Такие конфликты будут редки, если будут соблюдены правила именования, описанные в §6.1. Тем не менее, конфликты могут возникать непреднамеренно, по мере развития типов, разработанных разными программистами или разными организациями. Например, типы, методы и поля могут иметь одинаковые имена. Всегда возможно различить метод и поле с одинаковым именем, так как контекст использования всегда указывает, является ли метод предназначенным.

Язык программирования Java предоставляет механизмы управления доступом, чтобы предотвратить зависимость пользователей от пакета или класса от ненужных деталей реализации этого пакета или класса. Если доступ разрешен, то доступный элемент называется доступным.

Обратите внимание, что доступность — это статическое свойство, которое может быть определено на этапе компиляции; оно зависит только от типов и модификаторов объявления.

Квалифицированные имена являются средством доступа к членам пакетов и ссылочных типов. Когда имя такого члена классифицируется из контекста (§6.5.1) как квалифицированное имя типа (обозначающее член пакета или ссылочного типа, §6.5.5.2) или квалифицированное имя выражения (обозначающее член ссылочного типа, §6.5.6.2), применяется контроль доступа.

Например, оператор импорта одного типа (§7.5.1) должен использовать квалифицированное имя типа, поэтому имя импортируемого типа должно быть доступно из единицы компиляции, содержащей оператор импорта. Другой пример: объявление класса может использовать квалифицированное имя типа для суперкласса (§8.1.5), и вновь квалифицированное имя типа должно быть доступно.

Некоторые очевидные выражения «отсутствуют» в классификации контекста в §6.5.1: доступ к полю в Первичном элементе (§15.11.1), вызов метода в Первичном элементе (§15.12) и экземпляр созданного класса в квалифицированном создании экземпляра класса (§15.9). Каждое из этих выражений использует идентификаторы, а не имена, по причине, указанной в §6.2. Следовательно, контроль доступа к членам (поля, методы, типы) применяется явным образом выражениями доступа к полям, выражениями вызова методов и выражениями квалифицированного создания экземпляра класса. (Обратите внимание, что доступ к полю также может быть обозначен квалифицированным именем, встречающимся как постфиксное выражение.)

Обратите внимание, что квалифицированные имена, выражения доступа к полям, выражения вызова методов и выражения квалифицированного создания экземпляра класса синтаксически похожи в том, что появляется маркер «.», предваряемый указанием пакета, типа или выражения, имеющего тип, и за которым следует Идентификатор, который называет член пакета или типа. (Маркер new стоит между . и Идентификатором в выражении квалифицированного создания экземпляра класса.)

Многие операторы и выражения позволяют использовать типы вместо имён типов. Например, объявление класса может использовать параметризованный тип (§4.5) для обозначения суперкласса. Поскольку параметризованный тип не является квалифицированным именем типа, необходимо, чтобы объявление класса явно выполняло контроль доступа к обозначенному суперклассу. Следовательно, большинство операторов и выражений, которые предоставляют контексты в §6.5.1 для классификации ИмениТипа, также должны выполнять свои проверки доступа.

Помимо доступа к членам пакета или ссылочного типа, существует вопрос доступа к конструкторам ссылочного типа. Контроль доступа должен проверяться при явном или неявном вызове конструктора. Следовательно, контроль доступа проверяется оператором явного вызова конструктора (§8.8.7.1) и выражением создания экземпляра класса (§15.9.3). Эти «ручные» проверки необходимы, потому что §6.5.1 игнорирует явные вызовы конструкторов (потому что они ссылаются на имена конструкторов косвенно) и не осведомлен о различии между типом класса, обозначаемым неквалифицированным выражением создания экземпляра класса, и конструктором этого типа класса. Кроме того, конструкторы не имеют квалифицированных имён, поэтому мы не можем полагаться на то, что контроль доступа проверяется во время классификации квалифицированных имён типов.

Доступность влияет на наследование членов класса (§8.2), включая скрытие и переопределение методов (§8.4.8.1).