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

Объявленная сущность — это одна из следующих:

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

Объявление типа, который не является обобщенным (class C ...), объявляет одну сущность: необобщенный тип (C). Необобщенный тип не является сырым типом, несмотря на синтаксическое сходство. Напротив, объявление обобщенного типа (class C<T> ... или interface C<T> ...) объявляет две сущности: обобщенный тип (C<T>) и соответствующий необобщенный тип (C). В этом случае, смысл термина C зависит от контекста, в котором он появляется:

14 контекстов без обобщений следующие:

Первые одиннадцать контекстов без дженериков соответствуют первым одиннадцати синтаксическим контекстам для TypeName в §6.5.1. Двенадцатый контекст без дженериков — это место, где квалифицированное ExpressionName, например, C.x, может включать TypeName C для обозначения доступа к статическому члену. Частое использование TypeName в этих двенадцати контекстах важно: оно указывает, что эти контексты включают использование типа с низким приоритетом. В отличие от этого, тринадцатый и четырнадцатый контексты без дженериков используют ClassType, указывая, что блоки throws и catch используют типы на первом уровне, подобно, скажем, декларациям полей. Определение этих двух контекстов как контекстов без дженериков объясняется тем, что тип исключения не может быть параметризован.

Обратите внимание, что производство ClassType допускает аннотации, поэтому можно аннотировать использование типа в блоке throws или catch, тогда как производство TypeName не допускает аннотаций, поэтому нельзя аннотировать имя типа, например, в декларации импорта одного типа.

Рекомендации по именованию

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

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

Имена пакетов и модулей

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

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

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

com.nighthacks.scrabble.dictionary
org.openjdk.compiler.source.tree
net.jcip.annotations
edu.cmu.cs.bovik.cheese
gov.whitehouse.socks.mousefinder

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

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

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

com.nighthacks.scrabble
org.openjdk.compiler
net.jcip.annotations

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

Имя пакета или модуля не должно подразумевать, где пакет или модуль хранятся в Интернете. Например, пакет с именем edu.cmu.cs.bovik.cheese необязательно доступен из хоста cmu.edu или cs.cmu.edu или bovik.cs.cmu.edu. Предлагаемое соглашение для генерации уникальных имен пакетов и модулей — это просто способ присоединить соглашение об именовании пакетов и модулей к существующему, широко известному регистру уникальных имен вместо необходимости создания отдельного регистра для имен пакетов и модулей.

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

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

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, §15.27.1), параметр исключения (§14.20) и локальный класс (§14.3) могут быть упомянуты только с помощью простого имени, а не с помощью квалифицированного имени (§6.2).

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

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

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

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

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

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

Эти правила позволяют повторно объявлять переменную или локальный класс в объявлениях вложенных классов, которые встречаются в области действия переменной или локального класса; такие вложенные объявления классов могут быть локальными классами (§14.3) или анонимными классами (§15.9). Таким образом, объявление формального параметра, локальной переменной или локального класса может быть затемнено объявлением класса, вложенного в метод, конструктор или лямбда-выражение; а объявление параметра исключения может быть затемнено объявлением класса, вложенного в блок catch-инструкции.

Существует две альтернативные схемы обработки конфликтов имен, создаваемых параметрами лямбда-выражений и другими переменными, объявленными в лямбда-выражениях. Одна — имитировать объявления классов: как локальные классы, лямбда-выражения вводят новый «уровень» для имен, и все имена переменных за пределами выражения могут быть повторно объявлены. Другая — «локальная» стратегия: как catch-инструкции, for-циклы и блоки, лямбда-выражения работают на том же «уровне», что и окружающий контекст, и локальные переменные за пределами выражения не могут быть затемнены. Вышеприведённые правила используют локальную стратегию; нет специального разрешения, которое позволяет переменной, объявленной в лямбда-выражении, затемнять переменную, объявленную в окружающем методе.

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

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), применяется контроль доступа.

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

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

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

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

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