Начать занятия
I am ready for a long road flight for working with a week- or months-long projects.
Начать обучение
  • Блог
    →
  • Руководство Google по форматированию кода на Java. Часть 3

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

5 Именование
6 Практика программирования
7. Javadoc

5 Именование

5.1 Общие правила для всех идентификаторов

Идентификаторы используют только буквы и цифры ASCII и, в некоторых отмеченных ниже случаях, символы подчеркивания.
Таким образом, каждое допустимое имя идентификатора соответствует регулярному выражению \w+. (буквенно-цифровой символ, встречающийся один или более раз — примечание переводчика ).
Стилю данного руководства не соответствуют имена, использующие специальные суффиксы или префиксы, например: name_, mName, s_name или kName.

5.2 Правила для разных типов идентификаторов

5.2.1 Имена пакетов и модулей
Имена пакетов и модулей используют только строчные буквы и цифры (без подчёркиваний). Последовательные слова просто объединяются.
Правильно: com.example.deepspace
Неправильно: com.example.deepSpace или com.example.deep_space
5.2.2 Имена классов
Имена классов именуются в стиле UpperCamelCase (с заглавной первой буквой).
Имена классов обычно являются существительными или словосочетаниями с существительными. Например, Character или ImmutableList.
Имена интерфейсов также могут быть существительными или словосочетаниями с существительными (например, List), но иногда могут быть прилагательными или сочетаниями с прилагательными (например, Readable).
Не существует конкретных правил или устоявшихся соглашений для именования типов аннотаций.
Имя тестового класса заканчивается на `Test`, например `HashIntegrationTest`. Если он тестирует один класс, его имя состоит из имени этого класса плюс `Test`, например, `HashImplTest`.
5.2.3 Имена методов
Имена методов записываются в стиле lowerCamelCase (с маленькой первой буквой).
Имена методов обычно являются глаголами или словосочетаниями с глаголами. Например, sendMessage или stop.
В именах методов тестов JUnit могут использоваться подчёркивания для разделения логических компонентов имени, причём каждый компонент записывается в стиле lowerCamelCase, например, transferMoney_deductsFromSource. Не существует единственно правильного способа именования тестовых методов.
5.2.4 Имена констант
Имена констант используют стиль UPPER_SNAKE_CASE: все буквы заглавные, каждое слово отделено от следующего одним символом подчеркивания. Но что именно считается константой?
Константами являются static final поля, содержимое которых является глубоко неизменяемым, а методы не имеют обнаруживаемых побочных эффектов. Такими константами являются примитивы, переменные типа String, неизменяемые классы и всё, что установлено в null. Если какое-либо наблюдаемое состояние объекта может измениться, он не является константой. Простого намерения никогда не изменять объект недостаточно.
Примеры: 
// Константы
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final Map<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // поскольку Joiner неизменяем
static final SomeMutableType[] EMPTY_ARRAY = {};

// Не константы
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final ImmutableMap<String, SomeMutableType> mutableValues =
    ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};
Имена констант обычно являются существительными или словосочетаниями с существительными.
5.2.5 Имена не константных полей
Имена не константных полей (статических или нет) записываются в стиле lowerCamelCase.
Имена таких полей обычно являются существительными или словосочетаниями с существительными. Например, computedValues или index.
5.2.6 Имена параметров
Имена параметров записываются в стиле lowerCamelCase.
В публичных методах следует избегать имен параметров, состоящих из одного символа.
5.2.7 Имена локальных переменных
Имена локальных переменных записываются в стиле lowerCamelCase.
Даже будучи финальными и неизменяемыми, локальные переменные не считаются константами и не должны оформляться в их стиле.
5.2.8 Имена переменных типа
Каждая переменная типа именуется одним из двух стилей:
  • Одна заглавная буква, опционально с последующей одной цифрой (например, E, T, X, T2)
  • Имя в форме, используемой для классов (см. Раздел 5.2.2), с добавлением заглавной буквы T (например, RequestT, FooBarT).

5.3 «Верблюжий» стиль (camelCase)

Иногда существует более одного способа преобразовать фразу на английском языке в «верблюжий» стиль, как например в случае с аббревиатурами или нестандартными выражениями вроде «IPv6» или «iOS».
Для повышения предсказуемости, данное руководство задает следующую (примерную) схему.
Начинаем с исходной формы имени:
1. Преобразуйте фразу в обычный ASCII и удалите все апострофы. Например, «Müller's algorithm» можно преобразовать в «Muellers algorithm»
2. Разделите полученный результат на слова, отбрасывая пробелы и оставшиеся знаки препинания (обычно дефисы):
  • рекомендация: если какое-либо слово уже имеет общепринятую форму в «верблюжьем» стиле, разделите его на составные части (например, «AdWords» преобразуется в «ad words»). Обратите внимание, что слово «iOS» записывается не совсем в «верблюжьем» стиле; оно не соответствует каким-либо соглашениям, поэтому данная рекомендация не применяется.
3. Теперь преобразуйте все в нижний регистр (включая аббревиатуры), затем измените в верхний регистр первый символ:
  • … в каждом слове, чтобы получить UpperCamelCase, или
  • … в каждом слове, кроме первого, чтобы получить lowerCamelCase
4. Наконец, объедините все слова в один идентификатор. Обратите внимание, что регистр исходных слов почти полностью игнорируется.
В очень редких случаях (например, многокомпонентные номера версий) может потребоваться использовать подчёркивания для разделения соседних чисел, поскольку числа не имеют вариантов верхнего и нижнего регистра.
Примеры:
*Допустимо, но не рекомендуется.
Примечание: некоторые слова в английском языке могут писаться через дефис по-разному: например, «nonempty» и «non-empty» оба правильны, поэтому имена методов checkNonempty и checkNonEmpty также оба правильны.

6 Практика программирования

6.1 Всегда используйте @Override
Аннотацию @Override следует указывать для метода, когда:
  • Метод класса переопределяет метод суперкласса
  • Метод класса реализует метод интерфейса
  • Метод интерфейса переопределяет метод суперинтерфейса
  • Метод-аксессор объявляется явно для компонента записи (record)
Исключение: аннотация может быть опущена, когда родительский метод помечен как @Deprecated.

6.2 Не игнорируйте пойманные исключения

Очень редко возникают ситуации, когда не нужно предпринимать никаких действий в ответ на пойманное исключение (типичным решением является занесение его в лог или, если исключение считается «невозможным», повторно выбросить его как AssertionError).
Ниже приведен пример с поясняющим комментарием, когда действительно уместно не предпринимать никаких действий в блоке catch:
try {
    int i = Integer.parseInt(response);
    return handleNumericResponse(i);
} catch (NumberFormatException ok) {
    // Это не число; это нормально, просто продолжаем
}
return handleTextResponse(response);

6.3 Обращение к статическим членам через имя класса

Обращаться к статическому члену класса необходимо через имя класса, а не по ссылке на объект или по выражению, возвращающему этот объект:
Foo aFoo = ...;
Foo.aStaticMethod(); // правильно
aFoo.aStaticMethod(); // неправильно
somethingThatYieldsAFoo().aStaticMethod(); // очень неправильно

6.4 Не используйте финализаторы

Не переопределяйте Object.finalize. Поддержка финализации запланирована к удалению.

7. Javadoc

7.1 Форматирование

7.1.1 Основная форма
Основной способ форматирования блоков Javadoc показана в следующем примере:
/**
 * Многострочный текст Javadoc пишется здесь,
 * с обычным переносом строк...
 */
public int method(String p1) { ... }
… или в одну строку: 
/** Особенно короткий текст Javadoc. */
В большинстве случаев следует использовать основной способ форматирования многострочных комментариев. Однострочная форма может использоваться, когда весь блок Javadoc (включая маркеры комментария) помещается в одну строку. Обратите внимание, что это применимо лишь тогда, когда нет блочных тегов, таких как @param.
7.1.2 Абзацы
Одна пустая строка, то есть строка, содержащая только выровненную начальную звездочку ( * ), используется между абзацами и перед группой блочных тегов, если таковые имеются. Каждый абзац, кроме первого, начинается с <p> непосредственно перед первым словом, без пробела после него. HTML-теги других блочных элементов, таких как <ul> или <table>, не предваряются тегом <p>.
7.1.3 Блочные тэги
Все блочные теги следует размещать в таком порядке: @param, @return, @throws, @deprecated. Эти четыре тега никогда не используются с пустым описанием. Если тег блока не помещается в одну строку, продолжение строки имеет отступ в четыре (или более) пробела от позиции @.

7.2 Краткое описание метода

Каждый блок Javadoc начинается с краткого описания. Это описание очень важно: оно является единственной частью текста, которая присутствует в определенных контекстах, таких как индексы классов и методов.
Это описание обычно состоит из словосочетания с существительным или глаголом, а не является законченным предложением. Он не начинается с A {@code Foo} is a… или This method returns…, а также не образует законченного повелительного предложения, например, Save the record. Однако описание должно начинаться с заглавной буквы и заканчиваться точкой, как если бы это было полноценное предложение.
Совет: Распространенной ошибкой является написание Javadoc в виде
/** @return the customer ID */.
Это неверно и должно быть исправлено на
/** Returns the customer ID. */.
или
/** {@return the customer ID} */

7.3 Где использовать Javadoc

Как минимум, Javadoc следует использовать для каждого видимого класса, члена или компонента записи, за исключением некоторых случаев, описанных ниже.
Класс верхнего уровня является видимым, если он public; член является видимым, если он public или protected и его содержащий класс видим; компонент записи является видимым, если его содержащая запись видима.
Дополнительное содержимое Javadoc также может присутствовать, как объяснено в Разделе 7.3.4.
7.3.1 Исключение: методы, описывающие себя
Javadoc опционален для простых и очевидных методов, таких как getFoo, в тех случаях, когда действительно нельзя сказать ничего более, чем «Возвращает foo».
Важно: неуместно ссылаться на это исключение, чтобы оправдать пропуск соответствующей информации, которую может потребоваться обычному читателю.
Например, для метода с названием getCanonicalName не опускайте документацию (с тем основанием, что имя метода говорит лишь /** Возвращает каноническое имя. */), если обычный человек, читающий код, может и не подозревать, что означает термин «каноническое имя»!
7.3.2 Исключение: переопределение
Javadoc не всегда сопровождает метод, который переопределяет метод из супер-класса (или супер-интерфейса).
7.3.4 Необязательный Javadoc
Прочие классы и члены сопровождаются Javadoc по необходимости или по желанию.
Всякий раз, когда комментарий реализации будет использоваться для определения общей цели или поведения класса или члена, этот комментарий записывается как Javadoc (с использованием /**).
Необязательный Javadoc не обязательно должен следовать правилам форматирования Разделов 7.1.2, 7.1.3 и 7.2, хотя это, конечно, рекомендуется.
Оригинал статьи «Google Java Style Guide»
Оцените статью, если она вам понравилась!