Руководство Google по форматированию кода на Java. Часть 2

4 Форматирование
Терминология
Тело класса, метода или конструктора относится к блочной конструкции.

Обратите внимание, что согласно Разделу 4.8.3.1, любой инициализатор массива также может рассматриваться как блочная конструкция.
4.1 Фигурные скобки
4.1.1 Фигурные скобки используются везде, где они могут быть использованы
Фигурные скобки используются в if, else, for, while и do-while, даже если тело выражения пустое или содержит лишь одну строку кода.
Другие необязательные фигурные скобки, например в лямбда-выражении, остаются необязательными.
4.1.2 Непустые блоки: стиль K & R
Фигурные скобки ставятся согласно стилю Кернигана и Ритчи («Египетские скобки») для непустых блоков и блочных конструкций (для наглядности мы решили добавить немного кода, демонстрирующего данные правила — примечание переводчика):

  • Перед открывающейся скобкой переход на новую строку не делается:

// правильно
if (true) {

// неправильно
if (true)
{

  • Переход на новую строку делается после открывающей скобки:

// правильно
while (true) {
    // some code

// неправильно
while (true) { // some code

  • Переход на новую строку делается перед закрывающей скобкой:

// правильно
for (true) {
    // some code
}

// неправильно
while (true) { /* some code */ }

// неправильно
if (true) {
    /* some code */ }

  • Переход на новую строку делается после закрывающей скобки, только если эта скобка завершает выражение или тело метода, конструктора или не анонимный класс. Переход на новую строку не делается после скобки, если за ней следует else, catch или точка с запятой
Примеры правильно примененных правил:

return () -> {
    while (condition()) {
        method();
   }
};

return new MyClass() {
    @Override public void method() {
        if (condition()) {
            try {
                something();
            } catch (ProblemException e) {
                recover();
            }
        } else if (otherCondition()) {
            somethingElse();
        } else {
            lastThing();
        }
    }
};
Некоторые исключения для перечислений приведены в Разделе 4.8.1
4.1.3 Пустые блоки могут быть сжатыми
Пустой блок или пустая блочная конструкция может следовать стилю K & R (как описано в Разделе 4.1.2). Также возможно, чтобы такой блок был закрыт сразу же после открытия, без символов или разрыва строки внутри {}. Это правило не относится к случаю, когда блок является частью многоблочного выражения, которое содержит if-else или try-catch-finally.

Примеры:

// Приемлемо
void doNothing() {}

// Также приемлемо
void doNothingElse() {
}

// Неприемлемо: нельзя использовать пустые блоки в многоблочном выражении
try {
    doSomething();
} catch (Exception e) {}
4.2 Два пробела для отступа
Каждый раз, когда открывается новый блок или блочная конструкция, смещение вправо увеличивается на два пробела (лучше на четыре — примечание переводчика). Когда блок заканчивается, начало следующей строки кода смещается на предыдущий уровень смещения. Уровень смещения применяется как к блоку, так и к комментариям в этом блоке (см. пример в Разделе 4.1.2).
4.3 Одно выражение на каждую строку
Каждое выражение завершается переходом на новую строку.
4.4 Ограничение ширины строки в 100 символов
Java-код имеет ограничение в 100 символов по ширине строки (из-за распространения широкоформатных мониторов, допустимой шириной является использование до 120 символов — примечание переводчика). Под «символом» понимается любой из элементов Unicode. За исключением случаев, описанных ниже, каждая строка с превышением ограничения по ширине, должна быть перенесена так, как это объяснено в Разделе 4.5.
Исключения:
  1. Строки, в которых соблюдение ограничения по ширине невозможно (например, длинная ссылка URL в Javadoc или длинная JSNI-ссылка на метод)
  2. Объявления package и import (см. Разделы 3.2 и 3.3)
  3. Строки с командами в комментариях, которые могут быть скопированы и вставлены для выполнения в терминале
  4. Очень длинные идентификаторы в тех редких случаях, когда они требуются, могут превышать ограничение по ширине
4.5 Перенос строки
Терминология
Когда код, который в другом случае мог бы быть расположен на одной строке, разделяется на несколько строк, это явление называется переносом строки.
Не существует общепринятой однозначной формулы, определяющей, как именно надо делать перенос строки в каждой ситуации. Очень часто имеется несколько способов переноса строки с одним и тем же фрагментом кода.
Обычно перенос делается во избежание переполнения строки по ширине. Но даже если код остался бы в пределах разрешенной ширины, то и он, по решению автора, может быть перенесен на новую строку.
Выделение вспомогательного метода или локальной переменной может решить проблему переполнения строки по ширине без переноса кода
4.5.1 Где делать перенос
Первое указание по переносу строки гласит: предпочтительнее делать перенос на более высоком синтаксическом уровне. Также:
1. Когда строка разрывается не на операторе присваивания, разрыв делается перед символом.
    Это правило также применимо к следующим «оператороподобным» символам:
    • разделяющая точка «.»
    • двойное двоеточие ссылочного метода «::»
    • амперсанд в скобках дженерика <T extends Foo & Bar>
    • разделитель в catch-блоке catch (FooException | BarException e)
    2. Когда строка переносится на операторе присваивания, перенос обычно делается после символа, но приемлемо и другое решение

    Это также применимо к двоеточию для цикла for-each.
    3. Имя метода или конструктора при переносе строки остается присоединенным к открывающей скобке «(»
    4. Запятая «,» при переносе строки остается с элементом, который ей предшествует
    5. Строка никогда не переносится непосредственно у стрелки лямбда-выражения, кроме случаев, когда его тело состоит из одного выражения без фигурных скобок:
    
    MyLambda<String, Long, Object> lambda =
            (String label, Long value, Object obj) -> {
                ...
            };
    
    Predicate<String> predicate = str ->
            longExpressionInvolving(str);
    
    Главная цель переноса строки — добиться ясности кода, но не обязательно наименьшего количества строк
    4.5.2 Смещение продолжения строки на 4 и более пробелов
    При переносе строки каждая следующая ее подстрока (каждое продолжение строки) смещается как минимум на 4 пробела относительно предыдущей.

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

    В Разделе 4.6.3 даются указания по использованию различного количества пробелов для выравнивания элементов кода относительно предыдущих строк.
    4.6 Пробелы и отступы
    4.6.1 Отступы
    Одна пустая строка всегда ставится:

    1. Между следующими друг за другом членами или инициализаторами класса: полями, конструкторами, методами, вложенными классами, статическими и динамическими блоками инициализации


    • исключение: пустая строка между двумя последовательными полями (без кода между ними) используется опционально. При необходимости пустые строки используются для логического группирования полей
    • исключение: пустые строки между константами класса enum (см. Раздел 4.8.1)
    2. В соответствии с другими разделами данного документа (например, с Разделом 3 и Разделом 3.3)

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

    Несколько последовательных пустых строк делать разрешается, но это не необходимо и не приветствуется.
    4.6.2 Пробелы
    Помимо требований самого языка или прочих правил данного документа, а также не считая литералов и комментариев (в т.ч. Javadoc), одиночные пробелы из таблицы ASCII могут присутствовать только в следующих местах:

    1. При разделении любого зарезервированного слова, такого как if, for или catch, и открывающей круглой скобки «(», которая следует за ним

    2. При разделении любого зарезервированного слова, такого как else или catch, и закрывающей фигурной скобки «}», которая следует за ним

    3. Перед любой открывающей фигурной скобкой «{», за исключением двух ситуаций:
    • @SomeAnnotation({a, b})
    • String[][] x = {{"foo"}}; - пробел между {{ не нужен согласно п. 8 ниже
    4. По обе стороны от любого бинарного или тернарного оператора

    Это правило также применимо к следующим операторам:
    • амперсанд внутри угловых скобок: <T extends Foo & Bar>
    • разделитель в блоке catch, содержащий несколько исключений: catch (FooException | BarException e)
    • двоеточие «:» в  for-each
    • стрелка в лямбда-выражении: (String str) -> str.length()
    Но это правило не применимо к операторам:
    • двойное двоеточие «::» ссылочного метода, которое пишется как Object::toString
    • разделяющая точка «.», которая пишется как object.toString()
    5. После «,:;» или закрывающей круглой скобки «)» при приведении типа

    6. По обе стороны от двойной косой черты «//» при создании комментария в той же строке кода. Здесь разрешены, но не необходимы несколько пробелов

    7. Между объявлением типа и именем переменной: List<String> list

    8. Опционально: внутри скобок инициализатора массива
    • new int[] {5, 6} и new int[] { 5, 6 } — оба варианта верные
    9. Между аннотацией типа и [] или ...

    Это правило не требует наличия или отсутствия пробелов в начале или конце строки; оно относится лишь к внутренним пробелам.
    4.6.3 Горизонтальное выравнивание не требуется никогда
    Терминология
    Горизонтальное выравнивание — это практика добавления различного числа дополнительных пробелов в вашем коде с целью сделать так, чтобы определенные элементы были расположены под другими элементами с предыдущей строки.
    Эта практика разрешена, но ее использование не требуется данным руководством. Также нет необходимости поддерживать соблюдение выравнивания в тех участках кода, где оно уже было применено.

    Пример с выравниванием и без него:
    
    private int x;       // хорошо
    private Color color; // и это тоже
    
    private int   x;      // разрешено, но при редактировании в будущем
    private Color color;  // можно оставить без выравнивания
    
    Выравнивание способствует читаемости кода, но создает проблемы с поддержкой такого кода в будущем. Допустим, требуется изменить только одну строку. Это изменение может исказить форматирование ранее принятого кода, что допускается. Но скорее всего, программист (возможно, вы) начнет корректировку количества пробелов на рядом стоящих строках, что, возможно, запустит целую череду исправлений. Изменение одной строки может активировать «взрывную волну» из бессмысленного труда (в худшем случае). Или, в лучшем случае, приведет к искажению информации в истории версий, ухудшит чтение кода и обострит конфликты слияния.
    4.7 Группирующие скобки рекомендованы
    Допускается не ставить группирующие скобки только тогда, когда автор кода и рецензент согласны в том, что нет разумной вероятности, что код будет неверно истолкован без скобок, и при этом скобки не облегчили бы его чтение. Нет причины полагать, что каждый, кто читает код, помнит наизусть всю таблицу приоритетов использования операторов Java.
    4.8 Особые конструкции
    4.8.1 Классы-перечисления
    После каждой запятой, которая следует за константой перечисления, разрыв строки необязателен. Дополнительные пустые строки (обычно только одна) также допускаются. Вот пример такого кода:
    
    private enum Answer {
        YES {
            @Override public String toString() {
                return "yes";
            }
        },
    
        NO,
        MAYBE
    }
    
    Код класса-перечисления без методов и комментариев, описывающих его константы, может быть представлен, как инициализатор массива (см. Раздел 4.8.3.1):
    
    private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }
    
    Так как перечисления — это классы, для них следует применять все прочие правила, применимые к классам.
    4.8.2 Объявления переменных
    4.8.2.1 Одна переменная на одно объявление
    Каждая переменная (поле или локальная) объявляется только по одной за раз: такие объявления, как int a, b; не используются.

    Исключение: Множественные объявления переменных допускаются в заголовке цикла for.
    4.8.2.2 Объявляйте переменные тогда, когда они нужны
    Локальные переменные необязательно должны объявляться в начале блока или блочной конструкции. Наоборот, локальные переменные необходимо объявлять непосредственно перед местом их первого использования, чтобы минимизировать область их действия. Обычно локальные переменные инициализируются в момент объявления, или же сразу после него.
    4.8.3 Массивы
    4.8.3.1 Инициализаторы массивов могут быть «блочными»
    Любой массив может быть инициализирован так, как если бы он был блочной конструкцией. К примеру, весь следующий код допустим (список примеров не полный):
    
    new int[] {           
        0, 1, 2, 3            
    }                       
                            
    new int[] {             
        0, 1,               
        2, 3
    }               
    
    new int[]
        {0, 1, 2, 3}     
    
    new int[] {
        0,
        1,
        2,
        3,
    }
    
    4.8.3.2 Никаких объявлений массивов в стиле языка С
    Квадратные скобки ставятся после типа, а не после переменной: String[] args, а не String args[].
    4.8.4 Оператор switch
    Терминология
    Внутри блока switch располагается одна или более групп операторов. Каждая группа состоит из одной или более меток (как case FOO:, так и default:), за которыми следует один или более операторов (или, в случае последней группы, ни одного или более).
    4.8.4.1 Смещение
    Как и в случае с любым другим блоком, содержимое блока switch смещается на 2 пробела.

    После метки блока switch делается перенос строки, а смещение увеличивается на 2 пробела, так же как при открытии блока. Каждая следующая метка возвращается на предыдущий уровень смещения, как при закрытии блока.
    4.8.4.2 Сквозной проход комментируется
    Внутри блока каждая группа операторов либо завершает досрочно switch (с помощью break, continue, return или выбросом исключения), либо помечается комментарием, чтобы обозначить, что выполнение кода будет или может быть продолжено в следующей группе. Достаточно любого комментария, передающего идею сквозного прохода (обычно // fall through). Такой особый комментарий не требуется в последней группе блока switch. Пример:
    
    switch (input) {
        case 1:
        case 2:
            prepareOneOrTwo();
            // fall through
        case 3:
            handleOneTwoOrThree();
            break;
        default:
            handleLargeNumber(input);
    }
    
    Обратите внимание, что комментарий ставится не после case 1, а лишь в конце группы операторов.
    4.8.4.3 Всегда используйте default
    Оператор switch должен содержать метку default, даже если в ней не присутствует код.

    Исключение: блок switch для типа enum может не использовать default, если он содержит явные случаи, охватывающие все возможные значения этого типа. Это позволяет среде разработки или другим инструментам статического анализа выдавать предупреждение о том, что некоторые случаи не охвачены.
    4.8.5 Аннотации
    Аннотации, применяемые к классу, методу или конструктору, следуют непосредственно после блока документации. Каждая аннотация указывается на собственной строке (то есть по одной аннотации на строку). Эти разрывы строки не являются переносами строки (см. Раздел 4.5), поэтому уровень отступа не увеличивается. Пример:
    
    @Override
    @Nullable
    public String getNameIfPresent() { ... }
    
    Исключение: одиночная аннотация без параметров может отображаться вместе с первой строкой сигнатуры, например:
    
    @Override public int hashCode() { ... }
    
    Аннотации, применяемые к полю, также появляются сразу после блока документации, но в этом случае несколько аннотаций (возможно, параметризованных) могут быть перечислены в одной строке, например:
    
    @Partial @Mock DataLoader loader;
    
    Не существует особых правил для форматирования аннотаций к параметрам, локальным переменным или типам.
    4.8.6 Комментарии
    Этот раздел посвящен комментариям реализации. Javadoc рассматривается отдельно в Разделе 7.

    Любому разрыву строки может предшествовать произвольное количество пробелов, за которым следует комментарий реализации. Такой комментарий делает строку непустой.
    4.8.6.1 Стиль блочного комментария
    Уровень отступа блочного комментария совпадает с окружающим кодом. Блочные комментарии могут быть как /* … */, так и // … Для многострочных комментариев вида /* … */ последующие строки должны начинаться с символа *, выравненного с символом * с предыдущей строки.
    
    /*
     * This is          // And so           /* Or you can
     * okay.            // is this.          * even do this. */
     */
    
    Комментарии не заключаются в прямоугольники, изображенные звездочками или другими символами.
    При написании многострочных комментариев используйте стиль /* … */, если хотите, чтобы средства автоматического форматирования кода делали перенос строки при необходимости (в стиле параграфов). Большинство средств форматирования не могут делать этого с блоками однострочных комментариев // …
    4.8.7 Модификаторы
    Модификаторы класса и полей, если они присутствуют, отображаются в порядке, рекомендованном спецификацией языка Java:
    
    public protected private abstract default static final transient volatile synchronized native strictfp
    
    4.8.8 Числовые литералы
    Тип long использует прописную букву L, а не строчную (чтобы не перепутать с цифрой 1). Например, 300_000_000L вместо 300_000_000l.
    Оригинал статьи Google Java Style Guide
    Оцените статью, если она вам понравилась!