I am ready for a long road flight for working with a week- or months-long projects.

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

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

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

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

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

5 Именование

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

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

Таким образом, каждому действительному имени идентификатора соответствует регулярное выражение \w+ (буквенно-цифровой символ, встречающийся один или более раз).

Стилю данного руководства не соответствуют имена, использующие специальные суффиксы или префиксы, например: name_, mName, s_name или kName.

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

5.2.1 Имена пакетов

Имена пакетов должны быть записаны в нижнем регистре, без использования camelCase или подчеркиваний.

Правильно: com.example.deepspace
Неправильно: com.example.deepSpace или com.example.deep_space

5.2.2 Имена классов

Имена классов пишутся в стиле UpperCamelCase (с заглавной первой буквой).

Имена классов обычно являются существительными или словосочетаниями с существительными. Например, Character или ImmutableList.

Имена интерфейсов также могут быть существительными или словосочетаниями с существительными (например, List), но иногда могут быть и прилагательными или сочетаниями прилагательных (например, Readable).

Не существует конкретных правил или даже устоявшихся соглашений для именования типов аннотаций.

Тестовые классы носят имя, которое начинается с имени класса, который они тестируют, и заканчивается словом Test. Например, HashTest или HashIntegrationTest.

5.2.3 Имена методов

Имена методов пишутся в стиле lowerCamelCase.

Имена методов обычно являются глаголами или словосочетаниями с глаголами. Например, sendMessage или stop.

Подчеркивания могут присутствовать в именах тестовых методов JUnit для разделения логических компонентов в имени. При этом каждый компонент пишется в стиле lowerCamelCase. Типичным шаблоном является <methodUnderTest>_<state>, например, pop_emptyStack. Не существует единственно верного пути в именовании тестовых методов.

5.2.4 Имена констант

Константы именуются в стиле CONSTANT_CASE: все буквы в верхнем регистре, каждое слово отделено от следующего подчеркиванием. Но что именно является константой?

Константы — это статические финальные поля, содержимое которых является неизменным, и методы, которые не имеют видимых побочных эффектов. Это относится к примитивам, String, неизменяемым типам и неизменяемым коллекциям неизменяемых типов. Если какое-либо наблюдаемое состояние объекта может измениться, он не является константой. Простого намерения никогда не изменять объект недостаточно.

Примеры:


// Константы
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

// Не константы
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 всякий раз, когда он действительно переопределяется. Это относится как к методу класса-потомка, переопределяющему метод класса-родителя, так и к методу интерфейса, переопределяющему метод супер-интерфейса.

Исключение:

Аннотация может быть опущена, если родительский метод помечен аннотацией @Deprecated.

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

Очень редко возникают ситуации, когда не нужно предпринимать ни каких действий в ответ на пойманное исключение (типичным решением является занесение в лог или, если это считается «невозможным», перебросить исключение как AssertionError).

Ниже приведен пример с поясняющим комментарием, когда действительно уместно не предпринимать никаких действий в блоке catch:


try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} catch (NumberFormatException ok) {
  // it's not numeric; that's fine, just continue
}
return handleTextResponse(response);

Исключение:

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


try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

6.3 Для статических членов используйте имя класса

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


Foo aFoo = ...;
Foo.aStaticMethod(); // good
aFoo.aStaticMethod(); // bad
somethingThatYieldsAFoo().aStaticMethod(); // very bad

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

Крайней редко необходимо переопределить метод Object.finalize.

Подсказка:

Не делайте этого. Если вам действительно это нужно, сначала прочитайте и очень тщательно осмыслите Effective Java Item 7, «Avoid Finalizers», а затем — не делайте этого.

7. Javadoc

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

7.1.1 Основная форма

Простое форматирование блоков Javadoc соответствует данному примеру:


/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

… или в одну строку:


/** An especially short bit of Javadoc. */

Простая форма применима всегда. Однострочная форма может быть применена, когда весь блок Javadoc (включая маркеры комментариев) может поместиться на одной строке. Обратите внимание, что это применимо лишь тогда, когда в блоке нет таких тэгов, как @return.

7.1.2 Параграфы

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

7.3 Когда применяется Javadoc

Javadoc присутствует по меньшей мере в каждом public классе и в каждом public и protected члене такого класса, за исключением некоторых случаев, описанных ниже.

Дополнительный Javadoc может присутствовать, как это разъяснено в Разделе 7.3.4, Необязательный Javadoc.

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»

Оцените статью, если она вам понравилась!