I am ready for a long road flight for working with a week- or months-long projects.
Руководство Google по форматированию кода на Java. Часть 1
1 Введение
В данном документе описаны стандарты написания кода на языке программирования Java в корпорации Google. Исходный код Java считается соответствующим этим стандартам тогда и только тогда, когда он удовлетворяет всем описанным в документе правилам.
Затронутые в руководстве темы касаются не только эстетической стороны форматирования кода, но и других типов соглашений или стандартов кодирования. Тем не менее, данный документ концентрируется в первую очередь на определении строгих правил, которым мы повсеместно следуем, и не дает рекомендаций, которые могут быть неверно применены (как человеком, так и машинными инструментами).
1.1 Терминология
В рамках этого руководства определены следующие термины:
1. Термин класс используется для обозначения «обычного» класса, перечислений, интерфейса или типа аннотации (@interface)
2. Термин член класса используется для обозначения вложенного класса, поля, метода или конструктора, то есть для всех элементов класса высокого уровня, кроме блоков инициализации и комментариев
3. Термин комментарий всегда относится к комментариям реализации. Мы не используем словосочетание «комментарии к документации», а вместо этого используем термин «Javadoc»
Остальная терминология будет даваться по мере необходимости в разных местах данного руководства.
1.2 Примечание к руководству
Примеры кода в данном документе не демонстрируют единственно верный стилистический подход к его форматированию, хотя и используются в нашем руководстве.
2 Исходный файл. Основы
2.1 Имя файла
Имя исходного файла состоит из имени одного конкретного класса верхнего уровня, находящегося в нем. Имя является регистрозависимым и заканчивается расширением .java
2.2 Кодировка файла: UTF-8
Для файлов с кодом используется кодировка UTF-8.
2.3 Специальные символы
2.3.1 Символы пробела
Помимо последовательности символов конца строки, горизонтальный символ пробела ASCII (0×20) является единственным символом-разделителем, встречающимся в исходном файле. Это означает, что:
- Все прочие пробельные символы в символьных и строковых литералах экранируются
- Символы табуляции не используются для отступов
2.3.2 Специальные экранирующие последовательности
Для каждого символа, для которого существует специальная экранирующая последовательность (\b, \t, \n, \f, \r, \", \' и \\), предпочтительнее использовать именно ее вместо соответствующего ей восьмеричного значения (например, \012) или кода Unicode (например, \u000a).
2.3.3 Символы не из таблицы ASCII
Для символов не из таблицы ASCII используется символ Unicode (например, ∞) или эквивалентная экранирующая последовательность (например, \u221e). Выбор отдается в пользу тех символов, которые делают код более понятным и читаемым.
При использовании экранирующих последовательностей и, если это оправдано, при применении непосредственно символов Unicode, рекомендуется такой код сопровождать поясняющими комментариями
Никогда не делайте ваш код менее читаемым только из опасения, что некоторые программы не смогут правильно обработать символы не из таблицы ASCII. Если такое происходит, такие программы работают неверно и их нужно исправить
3 Структура исходного файла
Исходный файл состоит из следующих элементов (в указанном порядке):
- Информация о лицензии или авторских правах, если имеется
- Объявление пакета
- Объявление импортов
- Объявление одного класса верхнего уровня
Используйте только одну пустую строку в коде для разделения перечисленных элементов друг от друга.
3.1 Информация о лицензии или авторских правах, если имеется
Информация о лицензии или авторских правах должна быть размещена в том файле, к которому она относится.
3.2 Объявление пакета
Пакет объявляется без переноса строки. Ограничение на длину строки (Раздел 4.4) на объявление пакета не распространяется.
3.3 Объявления импортов
3.3.1 Символ подстановки при объявлении импортов
Символ * (подстановки) при объявлении импортов, статических или нет, не используется.
3.3.2 Перенос строки
Импорты объявляются без переноса строки. Ограничение на ширину строки на них не распространяется.
3.3.3 Упорядочивание и интервал
Импорты упорядочиваются следующим образом:
- Все статические импорты размещаются и группируются в одном блоке
- Все не статические импорты размещаются в другом блоке
Если объявляются как статические, так и не статические импорты, то эти блоки нужно разделить одной пустой строкой. Других пустых строк между операторами импорта быть не должно.
Внутри каждого блока импортируемые классы следуют в порядке сортировки ASCII-символов.
3.3.4 Статический импорт вложенных классов
Статический импорт не используется для статических вложенных классов. Такие классы импортируются с объявлением обычного импорта.
3.4 Объявление класса
3.4.1 Объявляется ровно один класс верхнего уровня
Каждый класс верхнего уровня располагается в своем исходном файле.
3.4.2 Упорядочивание содержимого класса
Порядок, выбираемый при расположении членов и блоков инициализации класса, может оказать большое влияние на легкость понимания кода. Однако для этого не существует единого правильного рецепта: разные классы могут упорядочивать свое содержимое по-разному.
Важно то, чтобы у каждого класса был такой логический порядок расположения содержимого, который позволил бы программисту, сопровождающему этот код, объяснить его.
3.4.2.1 Перегруженный код не должен быть разделен
Когда у класса есть несколько конструкторов или методов с одинаковым именем, они должны располагаться последовательно, без вставок другого кода между ними. Это правило применяется даже если модификаторы, такие как static или private, различаются между методами.
Оригинал статьи «Google Java Style Guide»
Оцените статью, если она вам понравилась!