Глава 6. Имена

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

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

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

Объявление обобщенного класса или интерфейса (class C<T> ... или interface C<T> ...) вводит как класс с именем C, так и семейство типов: необработанный тип C, параметризованный тип C<Foo>, параметризованный тип C<Bar> и т. д.

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

15 необобщенных контекстов следующие:

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

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

Правила именования

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

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

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

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

Если уникальные имена пакетов не используются, могут возникнуть конфликты имён пакетов далеко от места создания любого из конфликтующих пакетов. Это может создать ситуацию, которую сложно или невозможно разрешить пользователю или программисту. Классы 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 Platform.

Имя пакета или модуля не должно подразумевать, где пакет или модуль хранятся в Интернете. Например, пакет с именем 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;
}

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

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

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

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

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

Считается, что объявление находится в области действия в определенной точке программы тогда и только тогда, когда область действия объявления включает эту точку.

Область действия объявления наблюдаемого верхнего уровня пакета (§7.4.3) охватывает все наблюдаемые единицы компиляции, связанные с модулями, для которых пакет имеет уникальную видимость (§7.4.3).

Объявление пакета, который не наблюдаем, никогда не находится в области действия.

Объявление подпакета никогда не находится в области действия.

Пакет java всегда находится в области действия.

Область действия класса или интерфейса, импортированного объявлением импорта одного типа (§7.5.1) или объявлением импорта по требованию типа (§7.5.2), — это объявление модуля (§7.7) и все объявления классов и интерфейсов (§8.1, §9.1) в единице компиляции, в которой появляется объявление import, а также все аннотации к объявлениям модуля или пакета этой единицы компиляции.

Область действия члена, импортированного объявлением импорта одного статического члена (§7.5.3) или объявлением импорта статических членов по требованию (§7.5.4), — это объявление модуля и все объявления классов и интерфейсов в единице компиляции, в которой находится объявление import, а также все аннотации к объявлениям модуля или пакета этой единицы компиляции.

Область действия верхнего уровня класса или интерфейса (§7.6) — это все объявления классов и интерфейсов в пакете, в котором объявлен верхнеуровневый класс или интерфейс.

Область действия объявления члена m, объявленного в классе или интерфейсе C или унаследованного от него (§8.2, §9.2) — это весь текст C, включая объявления вложенных классов или интерфейсов.

Область действия формального параметра метода (§8.4.1), конструктора (§8.8.1) или лямбда-выражения (§15.27) — это весь текст метода, конструктора или лямбда-выражения.

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

Область действия параметра типа интерфейса (§9.1.2) — это раздел параметров типа объявления интерфейса, раздел параметров типа любого суперинтерфейса объявления интерфейса и тело интерфейса.

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

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

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

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

Область действия локальной переменной, объявленной в блоке с помощью оператора объявления локальной переменной (§14.4.2), — это остальная часть блока, начиная с инициализатора объявления и включая все последующие объявления в операторе объявления локальной переменной.

Область действия локальной переменной, объявленной в части ForInit оператора цикла basic for (§14.14.1) включает в себя:

Область действия локальной переменной, объявленной в заголовке оператора цикла enhanced for (§14.14.2), — это содержащаяся инструкция Statement.

Область действия локальной переменной, объявленной в спецификации ресурсов оператора try-with-resources (§14.20.3) — это область от объявления вправо до остальной части спецификации ресурсов и всего блока try, связанного с оператором try-with-resources.

Перевод оператора try-with-resources подразумевает вышеупомянутое правило.

Область действия параметра обработчика исключения, объявленного в блоке catch оператора try (§14.20) — это весь блок, связанный с catch.

package points;
class Point {
    int x, y;
    PointList list;
    Point next;
}

class PointList {
    Point first;
}

class Test1 {
    static int x;
    public static void main(String[] args) {
        int x = x;
    }
}

class Test2 {
    static int x;
    public static void main(String[] args) {
        int x = (x=2)*2;
        System.out.println(x);
    }
}

4

class Test3 {
    public static void main(String[] args) {
        System.out.print("2+1=");
        int two = 2, three = two + 1;
        System.out.println(three);
    }
}

2+1=3

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

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

Видно, что область действия объявления переменной шаблона — это понятие, зависящее от потока, аналогичное определенному присваиванию (§16 (Определённое присваивание)). Правила, определённые в остальной части этого раздела, умышленно имеют сходную форму с правилами определённого присваивания.

Анализ опирается на технический термин «введённый», который имеет следующий вид:

Простейший пример — переменная шаблона s вводится выражением a instanceof String s при истинном значении. Другими словами, если значение выражения равно true, то сопоставление шаблонов должно было быть успешным, а значит, переменная шаблона должна была получить значение.

В противоположность этому, переменная шаблона t вводится выражением !(b instanceof Integer t) при ложном значении. Это связано с тем, что сопоставление шаблонов могло быть успешным только в том случае, если значение выражения равно false.

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

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

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

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

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

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

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

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

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

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

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}

class Test4 {
    static void test(Object a, Object b, Object c) {
        if (a instanceof Point p) {
            System.out.println("a is a point ("+p.x+","+p.y+")");
        }
        if (b instanceof Point p){
            System.out.println("b is a point ("+p.x+","+p.y+")");
        } else if (c instanceof Point p) {
            System.out.println("c is a point ("+p.x+","+p.y+")");
        }
    }

    public static void main(String[] args) {
        Point p = new Point(2,3);
        Point q = new Point(4,5);
        Point r = new Point(6,7);
        test(p, q, r);
    }
}

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}

class Test5 {
    static void test(Object a, Object b, Object c) {
        if (a instanceof Point p) {
            System.out.println("a is a point ("+p.x+","+p.y+")");
	    
            if (b instanceof Point p) {  // compile-time error
                System.out.println("b is a point ("+p.x+","+p.y+")"); 
            }
        }
    }

    public static void main(String[] args) {
        Point p = new Point(2,3);
        Point q = new Point(4,5);
        Point r = new Point(6,7);
        test(p, q, r);

        if (new Object() instanceof Point q)  // compile-time error
            System.out.println("I get your point");
    }
}

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

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

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

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

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

Например, объявление импорта одного типа использует квалифицированное имя типа (§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).