Руководство google по форматированию кода на java
Тело класса, метода или конструктора относится к блочной конструкции.
Обратите внимание, что согласно Разделу 4.8.3.1, любой инициализатор массива также может рассматриваться как блочная конструкция.
4.1 Фигурные скобки4.1.1 Фигурные скобки используются везде, где они могут быть использованы
Фигурные скобки используются в if, else, for, while и do-while, даже если тело выражения пустое или содержит лишь одну строку кода.
4.1.2 Непустые блоки: стиль K & R
Фигурные скобки ставятся согласно стилю Кернигана и Ритчи («Египетские скобки») для непустых блоков и блочных конструкций:
- Перед открывающейся скобкой переход на новую строку не делается:
- Переход на новую строку делается после открывающей скобки:
- Переход на новую строку делается перед закрывающей скобкой:
- Переход на новую строку делается после закрывающей скобки, только если эта скобка завершает выражение или тело метода, конструктора или не анонимный класс. Переход на новую строку не делается после скобки, если за ней следует else, catch или точка с запятой
Некоторые исключения для перечислений приведены в Разделе 4.8.1
4.1.3 Пустые блоки могут быть сжатыми
Пустой блок или пустая блочная конструкция может следовать стилю K & R (как описано в Разделе 4.1.2). Также возможно, чтобы такой блок был закрыт сразу же после открытия, без символов или разрыва строки внутри <>. Это правило не относится к случаю, когда блок является частью многоблочного выражения, которое содержит if-else или try-catch-finally.
4.2 Два пробела для отступа Каждый раз, когда открывается новый блок или блочная конструкция, смещение вправо увеличивается на два пробела. Когда блок заканчивается, начало следующей строки кода смещается на предыдущий уровень смещения. Уровень смещения применяется как к блоку, так и к комментариям в этом блоке (см. пример в Разделе 4.1.2).4.3 Одно выражение на каждую строку
Каждое выражение завершается переходом на новую строку. 4.4 Ограничение ширины строки в 100 символов Java-код имеет ограничение в 100 символов по ширине строки. Под «символом» понимается любой из элементов Unicode. За исключением случаев, описанных ниже, каждая строка с превышением ограничения по ширине, должна быть перенесена так, как это объяснено в Разделе 4.5.
Исключения:
- Строки, в которых соблюдение ограничения по ширине невозможно (например, длинная ссылка URL в Javadoc или длинная JSNI-ссылка на метод)
- Объявления package и import (см. Разделы 3.2 и 3.3)
- Строки с командами в комментариях, которые могут быть скопированы и вставлены для выполнения в терминале
Терминология Когда код, который в другом случае мог бы быть расположен на одной строке, разделяется на несколько строк, это явление называется переносом строки. Не существует общепринятой однозначной формулы, определяющей, как именно надо делать перенос строки в каждой ситуации. Очень часто существует несколько способов переноса строки с одним и тем же фрагментом кода.
Обычно перенос делается во избежание переполнения строки по ширине. Но даже если код остался бы в пределах разрешенной ширины, то и он, по решению автора, может быть перенесен на новую строку.
Выделение вспомогательного метода или локальной переменной может решить проблему переполнения строки по ширине без переноса кода 4.5.1 Где делать перенос
Первое указание по переносу строки гласит: предпочтительнее делать перенос на более высоком синтаксическом уровне. Также:
1. Когда строка разрывается не на операторе присваивания, разрыв делается перед символом.
Это правило также применимо к следующим «оператороподобным» символам:
- разделяющая точка «.»
- двойное двоеточие ссылочного метода «::»
- амперсанд в скобках дженерика <T extends Foo & Bar>
- разделитель в catch-блоке catch (FooException | BarException e)
2. Когда строка переносится на операторе присваивания, перенос обычно делается после символа, но приемлемо и другое решение
Это также применимо к двоеточию для цикла for-each.
4. Запятая «,» при переносе строки остается с элементом, который ей предшествует 5. Строка никогда не переносится непосредственно у стрелки лямбда-выражения, кроме случаев, когда его тело состоит из одного выражения без фигурных скобок:
Главная цель переноса строки — добиться ясности кода, но не обязательно наименьшего количества строк 4.5.2 Смещение продолжения строки на 4 и более пробелов
При переносе строки каждая следующая ее подстрока (каждое продолжение строки) смещается как минимум на 4 пробела относительно предыдущей.
Когда продолжений строки несколько, смещение может варьироваться в пределах 4 пробелов по желанию автора. По общему правилу, два продолжения строки могут иметь одинаковое смещение тогда и только тогда, когда они начинаются с синтаксически параллельных элементов.
В Разделе 4.6.3 даются указания по использованию различного количества пробелов для выравнивания элементов кода относительно предыдущих строк.
Одна пустая строка всегда ставится:
1. Между следующими друг за другом членами или инициализаторами класса: полями, конструкторами, методами, вложенными классами, статическими и динамическими блоками инициализации
- исключение: пустая строка между двумя последовательными полями (без кода между ними) используется опционально. При необходимости пустые строки используются для логического группирования полей
- исключение: пустые строки между константами класса enum (см. Раздел 4.8.1)
Пустая строка также может быть использована повсеместно для повышения читаемости кода, например, между выражениями для организации кода в логические подразделы. Пустая строка перед первым членом класса, или блоком инициализации, или после последнего члена, или блока инициализации класса не приветствуется, но и не возбраняется.
Несколько последовательных пустых строк делать разрешается, но это не необходимо и не приветствуется.
Помимо требований самого языка или прочих правил данного документа, а также не считая литералов и комментариев (в т.ч. Javadoc), одиночные пробелы из таблицы ASCII могут присутствовать только в следующих местах:
1. При разделении любого зарезервированного слова, такого как if, for или catch, и открывающей круглой скобки «(», которая следует за ним
2. При разделении любого зарезервированного слова, такого как else или catch, и закрывающей фигурной скобки «>», которая следует за ним
Существуют соглашения, по поводу использования Java библиотек и инструментов для Android. В некоторых случаях соглашения могут быть изменены, например, в таких как использование старого кода, который, возможно, использует неодобренный паттерн или библиотеку.
Правила Java стиля
Программы гораздо проще поддерживать, когда все файлы имеют согласованный стиль. Мы следуем стандартному стилю программирования на Java, определенному Sun в их Code Conventions for the Java Programming Language, с несколькими исключениями и дополнениями. Данное руководство по стилю является подробным и всесторонним, а также широко используется Java сообществом.
Правила языка Java
Не игнорируйте исключения
Возможно, вам захочется написать код, который игнорирует исключения, например:
-
Перебрасывайте исключения к вызывающему методу.
Не перехватывайте обобщенные исключения
Иногда бывает заманчиво полениться с обработкой исключений и написать что-то вроде этого:
Вам не следует так делать. Суть в том, что возможно появление исключения, которого вы не ожидали и, в итоге, ошибка будет отлавливаться на уровне приложения. То есть, если кто-то добавит новый тип исключения, то компилятор не сможет вам помочь понять, что это другая ошибка.
Существуют редкие исключения из этого правила: определенный тестовый код, или код верхнего уровня, где вы хотите перехватывать все типы ошибок (для того, чтобы предотвратить их отображение в пользовательском интерфейсе, или чтобы продолжить какую-то пакетную задачу).
- Перехватывайте каждое исключение отдельно в блоке catch, после одиночного try. Возможно это неудобно, но всё равно это предпочтительный способ для перехвата всех исключений.
- Измените ваш код для более гранулированной обработки ошибок с несколькими блоками try. Отделите IO от парсинга, обрабатывайте ошибки отдельно в каждом случае.
- Перебросьте исключение. Во многих случаях вам не нужно обрабатывать все исключения на текущем уровне, просто позвольте методу перебросить их.
Финализаторы
Что это: Финализаторы — это способ запускать программный код перед тем как объект собирается сборщиком мусора.
За: могут быть полезны при очистке, в особенности внешних ресурсов.
Против: нет никаких гарантий того, когда будет вызван финализатор, и, вообще, будет ли он вызван.
Решение: Мы не используем финализаторы. В большинстве случаев, всё то, что вам нужно от финализатора, вы сможете сделать при помощи обработки исключений. Если вам действительно нужен финализатор, то объявите метод close() и задокументируйте, когда он точно будет вызываться.
Импорты
Групповой символ в импортах
Комментарии/Javadoc
Каждый файл должен иметь объявление об авторских правах в самом начале. Далее идут объявления операторов package и import, причем каждый блок разделяется пустой строкой. За ними следуют объявления класса или интерфейса. Опишите, что делает класс в Javadoc-комментариях.
Каждый класс и нетривиальный public метод должен содержать Javadoc, по крайней мере с одной фразой, описывающей что он делает. Фраза должна начинаться с описательного глагола 3-го лица. Примеры:
Вам не нужно описывать Javadoc для тривиальных get и set методов, таких как setFoo(), если ваш Javadoc говорит только «sets Foo». Если метод делает что-то более сложное (например, соблюдение неких ограничений, или если его действия имеют важный эффект вне его самого), тогда его обязательно нужно задокументировать. И если это не просто объяснение того, что означает Foo, то вам также следует его задокументировать.
Вообще, любой метод, который вы написали получает пользу от Javadoc, неважно public он или нет. Public методы являются частью API, и поэтому они требуют описания в Javadoc.
Для написания Javadoc'ов вам следует придерживаться Sun Javadoc conventions.
Короткие методы
Методы должны быть небольшими и решающими конкретную задачу настолько, насколько это возможно. Однако, понятно, что иногда большие методы бывают целесообразны, так что нет строгого ограничения на длину метода. Если метод превышает 40 строк, то вам, возможно, стоит подумать о том, можно ли его разбить на части, не нарушив структуры программы.
Локальные переменные
Область видимости локальных переменных должна сводиться к минимуму. Делая это, вы улучшаете читаемость и поддерживаемость кода, а также уменьшаете вероятность ошибок. Каждая переменная должна объявляться в самом глубоком блоке, который окружает все возможные места использования переменной.
Локальные переменные должны объявляться в том месте, где впервые необходимо её использовать. Почти каждая локальная переменная нуждается в инициализаторе. Если вы еще не знаете, как точно инициализировать переменную, то вам следует отложить её объявление, пока вы это не узнаете.
Существует одно исключение, касательно блока try-catch. Если переменная инициализируется при помощи оператора return метода, который выбрасывает проверяемое исключение, то она должна инициализироваться в блоке try. Если же переменная должна использоваться вне блока try, тогда она объявляется перед ним, неважно, знаете ли вы как её точно нужно инициализировать:
Но даже этот случай можно обойти при помощи инкапсуляции блока try-catch в методе.
Переменные в циклах должны объявляться внутри самого оператора, если только нет непреодолимой причины этого не делать.
Импорты
- Android импорты.
- Сторонние импорты (com, junit, net, org).
- java и javax.
- Отсортированы по алфавиту внутри каждой группы.
- Заглавные буквы должны быть впереди букв нижнего регистра (например, Z перед a).
- Главные группы должны разделяться пустой строкой.
- Импорты, которые люди хотят видеть в первую очередь, находятся вверху (android).
- Импорты, которые люди хотят видеть в последнюю очередь, находятся внизу (java).
- Люди могут с легкостью использовать этот стиль.
- IDE может придерживаться этого стиля.
Отступы
мы используем 4 пробела для блоков. Мы никогда не используем табуляцию. Мы используем 8 пробелов для переноса строк, включая вызовы функций и присваивания, например правильно так:
Названия полей
- Не static и не public имена начинаются c «m».
- static поля начинаются с «s».
- Другие поля начинаются с буквы нижнего регистра.
- Поля public static final (константы) пишутся полностью в верхнем регистре, с использованием подчеркивания (ALL_CAPS_WITH_UNDERSCORES)
Фигурные скобки
Для открывающих фигурные скобок не выделяется отдельная строка, они находятся в той же строке, что и код перед ними:
Мы требуем фигурные скобки для оператора условия. Исключением является, когда оператор условия и его тело помещаются в одну строку. То есть можно писать так:
Длина строки
Каждая строка текста в коде должна быть не длиннее 100 символов.
Исключение: если комментарий содержит пример команд, или URL (удобнее использовать copy/paste).
Исключение: строки импорта могут быть длиннее 100 символов, так как люди редко на них смотрят. Также это упрощает написание инструментов.
Сокращения в именах
Стиль TODO
Используйте комментарии TODO для кода, который является временным, краткосрочным, или хорошим, но не идеальным. Комментарий должен включать в себя «TODO:», например:
Если ваш комментарий имеет вид «В будущем сделать что-то», то убедитесь, что он включает в себя конкретную дату (1 января 2011 года), или конкретное событие «Удалить после выхода версии 2.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 и в тех случаях, когда применяются действующие символы Unicode, убедительно рекомендуем такой код сопровождать объясняющими комментариями
Пример;Примечание
Читайте также: