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

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

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

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

Если объявление не включает идентификатор, но вместо этого включает ключевое слово `_` (подчёркивание), то к сущности нельзя обратиться по имени. Следующие виды сущностей могут быть объявлены с помощью подчёркивания:

Локальная переменная, параметр исключения или лямбда-параметр, объявленный с помощью подчёркивания, называется, соответственно, необозначенной локальной переменной, необозначенным параметром исключения или необозначенным лямбда-параметром.

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

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

Имена полей

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

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

Область видимости локальной переменной, объявленной в спецификации ресурсов оператора try-with-resources try (§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: доступ к полю на Основном (§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).