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

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

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

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

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

Первые десять контекстов без дженериков соответствуют первым десяти синтаксическим контекстам для 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 можно использовать для изоляции пакетов с одинаковым именем друг от друга в тех случаях, когда у пакетов будут ограниченные взаимодействия, но не таким образом, чтобы это было прозрачно для простой программы.

Вы формируете уникальное имя пакета, сначала имея (или принадлежа к организации, которая имеет) доменное имя в Интернете, например, 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, §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) использует квалифицированное имя типа, поэтому указанный тип должен быть доступен из единицы компиляции, содержащей инструкцию импорта. Еще один пример — объявление класса может использовать квалифицированное имя типа для суперкласса (§8.1.5), и снова указанный тип должен быть доступен.

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

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

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

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