Основы программирования на Java
Основным строительным блоком программы на языке Java являются инструкции (statement). Каждая инструкция выполняет некоторое действие, например, вызовы методов, объявление переменных и присвоение им значений. После завершения инструкции в Java ставится точка с запятой (;). Данный знак указывает компилятору на конец инструкции. Например:
Данная строка представляет вызов метода System.out.println , который выводит на консоль строку «Hello Java!». В данном случае вызов метода является инструкцией и поэтому завершается точкой с запятой.
Кроме отдельных инструкций распространенной конструкцией является блок кода. Блок кода содержит набор инструкций, он заключается в фигурные скобки, а инструкции помещаются между открывающей и закрывающей фигурными скобками:
В этом блоке кода две инструкции, которые выводят на консоль определенную строку.
Выполнение программы. Метод main
Java является объектно-ориентированным языком, поэтому всю программу можно представить как набор взаимодействующих между собой классов и объектов. В первой главе при создании первого приложения программа была определена следующим образом:
То есть основу нашей программы составляет класс Program. При определении класса вначале идет модификатор доступа public , который указывает, что данный класс будет доступен всем, то есть мы сможем его запустить из командной строки. Далее идет ключевое слово class , а затем название класса. После названия класса идет блок кода, в котором расположено содержимое класса.
Входной точкой в программу на языке Java является метод main , который определен в классе Program. Именно с него начинается выполнение программы. Он обязательно должен присутствовать в программе. При этом его заголовок может быть только таким:
При запуске приложения виртуальная машина Java ищет в главном классе программы метод main с подобным заголовком, и после его обнаружения запускает его.
Вначале заголовка метода идет модификатор public , который указывает, что метод будет доступен извне. Слово static указывает, что метод main — статический, а слово void — что он не возвращает никакого значения. Далее в скобках у нас идут параметры метода — String args[] — это массив args, который хранит значения типа String, то есть строки. При запуске программы через этот массив мы можем передать в программу различные данные.
После заголовка метода идет его блок, который содержит набор выполняемых инструкций.
Комментарии
Код программы может содержать комментарии. Комментарии позволяют понять смысл программы, что делают те или иные ее части. При компиляции комментарии игнорируются и не оказывают никакого влияния на работу приложения и на его размер.
В Java есть два типа комментариев: однострочный и многострочный. Однострочный комментарий размещается на одной строке после двойного слеша //. А многострочный комментарий заключается между символами /* текст комментария */ . Он может размещаться на нескольких строках. Например:
Руководство Google по форматированию кода на Java
В данном документе описаны стандарты написания кода на языке программирования Java в корпорации Google. Исходный код Java считается соответствующим этим стандартам тогда и только тогда, когда он удовлетворяет всем описанным в документе правилам.
Затронутые в руководстве темы касаются не только эстетической стороны форматирования кода, но и других типов соглашений или стандартов кодирования. Тем не менее, данный документ концентрируется в первую очередь на определении строгих правил, которым мы повсеместно следуем, и не дает рекомендаций, которые могут быть неверно реализованы (как человеком, так и машинными инструментами).
1.1 Терминология
В рамках этого руководства определены следующие термины:
- Термин класс используется для обозначения «обычного» класса, перечислений, интерфейса или типа аннотации (@interface)
- Термин член класса используется для обозначения вложенного класса, поля, метода или конструктора, то есть для всех элементов класса высокого уровня, кроме блоков инициализации и комментариев
- Термин комментарий всегда относится к комментариям реализации. Мы не используем словосочетание «комментарии к документации», а вместо этого используем термин «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). Выбор отдается в пользу тех символов, которые делают код более понятным и читаемым.
| Пример | Примечание |
|---|---|
| String unitAbbrev = «μs» | Отлично: прекрасно воспринимается даже без комментария |
| String unitAbbrev = «\u03bcs» // «μs» | Допускается, но нет причин так делать |
| String unitAbbrev = «\u03bcs» // Греческая буква mu, «s» | Допускается, но неуклюже и может привести к ошибкам |
| String unitAbbrev = «\u03bcs» | Плохо: читающий понятия не имеет, что это такое |
| return ‘\ufeff’ + content // знак порядка байтов | Хорошо: используйте экранирование для непечатаемых символов и комментируйте при необходимости |
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 Перегруженный код не должен быть разделен
Когда у класса есть несколько конструкторов или методов с одинаковым именем, они должны располагаться последовательно, без вставок другого кода между ними.
4. Форматирование
Терминология
Тело класса, метода или конструктора относится к блочной конструкции.
Обратите внимание, что согласно Разделу 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 Перенос строки
Терминология
Когда код, который в другом случае мог бы быть расположен на одной строке, разделяется на несколько строк, это явление называется переносом строки.
Не существует общепринятой однозначной формулы, определяющей, как именно надо делать перенос строки в каждой ситуации. Очень часто существует несколько способов переноса строки с одним и тем же фрагментом кода.
Обычно перенос делается во избежание переполнения строки по ширине. Но даже если код остался бы в пределах разрешенной ширины, то и он, по решению автора, может быть перенесен на новую строку.
4.5.1 Где делать перенос
Первое указание по переносу строки гласит: предпочтительнее делать перенос на более высоком синтаксическом уровне. Также:
1. Когда строка разрывается не на операторе присваивания, разрыв делается перед символом.
Это правило также применимо к следующим «оператороподобным» символам:
- разделяющая точка «.»
- двойное двоеточие ссылочного метода «::»
- амперсанд в скобках дженерика <T extends Foo & Bar>
- разделитель в catch-блоке catch (FooException | BarException e)
Это также применимо к двоеточию для цикла for-each.
3. Имя метода или конструктора при переносе строки остается присоединенным к открывающей скобке «(»
4. Запятая «,» при переносе строки остается с элементом, который ей предшествует
5. Строка никогда не переносится непосредственно у стрелки лямбда-выражения, кроме случаев, когда его тело состоит из одного выражения без фигурных скобок:
4.5.2 Смещение продолжения строки на 4 и более пробелов
При переносе строки каждая следующая ее подстрока (каждое продолжение строки) смещается как минимум на 4 пробела относительно предыдущей.
Когда продолжений строки несколько, смещение может варьироваться в пределах 4 пробелов по желанию автора. По общему правилу, два продолжения строки могут иметь одинаковое смещение тогда и только тогда, когда они начинаются с синтаксически параллельных элементов.
В Разделе 4.6.3 даются указания по использованию различного количества пробелов для выравнивания элементов кода относительно предыдущих строк.
4.6 Пробелы и отступы
4.6.1 Отступы
Одна пустая строка всегда ставится:
1. Между следующими друг за другом членами или инициализаторами класса: полями, конструкторами, методами, вложенными классами, статическими и динамическими блоками инициализации
- исключение: пустая строка между двумя последовательными полями (без кода между ними) используется опционально. При необходимости пустые строки используются для логического группирования полей
- исключение: пустые строки между константами класса enum (см. Раздел 4.8.1)
Пустая строка также может быть использована повсеместно для повышения читаемости кода, например, между выражениями для организации кода в логические подразделы. Пустая строка перед первым членом класса, или блоком инициализации, или после последнего члена, или блока инициализации класса не приветствуется, но и не возбраняется.
Несколько последовательных пустых строк делать разрешается, но это не необходимо и не приветствуется.
4.6.2 Пробелы
Помимо требований самого языка или прочих правил данного документа, а также не считая литералов и комментариев (в т.ч. Javadoc), одиночные пробелы из таблицы ASCII могут присутствовать только в следующих местах:
1. При разделении любого зарезервированного слова, такого как if, for или catch, и открывающей круглой скобки «(», которая следует за ним
2. При разделении любого зарезервированного слова, такого как else или catch, и закрывающей фигурной скобки «>», которая следует за ним
3. Перед любой открывающей фигурной скобкой «<», за исключением двух ситуаций:
- @SomeAnnotation(
- String[][] x = <<«foo»>>; — пробел между << не нужен согласно п. 8 ниже
Это правило также применимо к следующим операторам:
- амперсанд внутри угловых скобок: <T extends Foo & Bar>
- разделитель в блоке catch, содержащий несколько исключений: catch (FooException | BarException e)
- двоеточие «:» в for-each
- стрелка в лямбда-выражении: (String str) -> str.length()
- двойное двоеточие «::» ссылочного метода, которое пишется как Object::toString
- разделяющая точка «.», которая пишется как object.toString()
6. По обе стороны от двойной косой черты «//» при создании комментария в той же строке кода. Здесь разрешены, но не необходимы несколько пробелов
7. Между объявлением типа и именем переменной:
8. Опционально: внутри скобок инициализатора массива
new int[] <5, 6>и new int[] < 5, 6 >— оба варианта верные
9. Между аннотацией типа и [] или…
Это правило не требует наличия или отсутствия пробелов в начале или конце строки; оно относится лишь к внутренним пробелам.
4.6.3 Горизонтальное выравнивание не требуется никогда
Терминология
Горизонтальное выравнивание — это практика добавления различного числа дополнительных пробелов в вашем коде с целью сделать так, чтобы определенные элементы были расположены под другими элементами с предыдущей строки.
Эта практика разрешена, но ее использование не требуется данным руководством. Также нет необходимости поддерживать соблюдение выравнивания в тех участках кода, где оно уже было применено.
Пример с выравниванием и без него:
Выравнивание способствует читаемости кода, но создает проблемы с поддержкой такого кода в будущем. Допустим, требуется изменить только одну строку. Это изменение может исказить форматирование ранее принятого кода, что допускается. Но, скорее всего, программист (возможно, вы) начнет корректировку количества пробелов на рядом стоящих строках, что, возможно, запустит целую череду исправлений. Изменение одной строки может активировать «взрывную волну» из бессмысленного труда (в худшем случае). Или, в лучшем случае, приведет к искажению информации в истории версий, ухудшит чтение кода и обострит конфликты слияния.
4.7 Группирующие скобки рекомендованы
Допускается не ставить группирующие скобки только тогда, когда автор кода и рецензент согласны в том, что нет разумной вероятности, что код будет неверно истолкован без скобок, и при этом скобки не облегчили бы его чтение. Нет причины полагать, что каждый, кто читает код, помнит наизусть всю таблицу приоритетов использования операторов Java.
4.8 Особые конструкции
4.8.1 Классы-перечисления
После каждой запятой, которая следует за константой перечисления, разрыв строки необязателен. Дополнительные пустые строки (обычно только одна) также допускаются. Вот пример такого кода:
Код класса-перечисления без методов и комментариев, описывающих его константы, может быть представлен, как инициализатор массива (см. Раздел 4.8.3.1):
Так как перечисления — это классы, для них следует применять все прочие правила, применимые к классам.
4.8.2 Объявления переменных
4.8.2.1 Одна переменная на одно объявление
Каждая переменная (поле или локальная) объявляется только по одной за раз: такие объявления, как int a, b; не используются.
Исключение: Множественные объявления переменных допускаются в заголовке цикла for.
4.8.2.2 Объявляйте переменные тогда, когда они нужны
Локальные переменные необязательно должны объявляться в начале блока или блочной конструкции. Наоборот, локальные переменные необходимо объявлять непосредственно перед местом их первого использования, чтобы минимизировать область их действия. Обычно локальные переменные инициализируются в момент объявления, или же сразу после него.
4.8.3 Массивы
4.8.3.1 Инициализаторы массивов могут быть «блочными»
Любой массив может быть инициализирован так, как если бы он был блочной конструкцией. К примеру, весь следующий код допустим (список примеров не полный):
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. Пример:
Обратите внимание, что комментарий ставится не после case 1, а лишь в конце группы операторов.
4.8.4.3 Всегда используйте default
Оператор switch должен содержать метку default, даже если в ней не присутствует код.
Исключение: блок switch для типа enum может не использовать default, если он содержит явные случаи, охватывающие все возможные значения этого типа. Это позволяет среде разработки или другим инструментам статического анализа выдавать предупреждение о том, что некоторые случаи не охвачены.
4.8.5 Аннотации
Аннотации, применяемые к классу, методу или конструктору, следуют непосредственно после блока документации. Каждая аннотация указывается на собственной строке (то есть по одной аннотации на строку). Эти разрывы строки не являются переносами строки (см. Раздел 4.5), поэтому уровень отступа не увеличивается. Пример:
Исключение: одиночная аннотация без параметров может отображаться вместе с первой строкой сигнатуры, например:
Аннотации, применяемые к полю, также появляются сразу после блока документации, но в этом случае несколько аннотаций (возможно, параметризованных) могут быть перечислены в одной строке, например:
Не существует особых правил для форматирования аннотаций к параметрам, локальным переменным или типам.
4.8.6 Комментарии
Этот раздел посвящен комментариям реализации. Javadoc рассматривается отдельно в Разделе 7.
Любому разрыву строки может предшествовать произвольное количество пробелов, за которым следует комментарий реализации. Такой комментарий делает строку непустой.
4.8.6.1 Стиль блочного комментария
Уровень отступа блочного комментария совпадает с окружающим кодом. Блочные комментарии могут быть как /* … */, так и // … Для многострочных комментариев вида /* … */ последующие строки должны начинаться с символа *, выравненного с символом * с предыдущей строки.
Комментарии не заключаются в прямоугольники, изображенные звездочками или другими символами.
4.8.7 Модификаторы
Модификаторы класса и полей, если они присутствуют, отображаются в порядке, рекомендованном спецификацией языка Java:
4.8.8 Числовые литералы
Тип long использует прописную букву L, а не строчную (чтобы не перепутать с цифрой 1). Например, 300_000_000L вместо 300_000_000l.
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. Типичным шаблоном является:
Не существует единственно верного пути в именовании тестовых методов.
5.2.4 Имена констант
Константы именуются в стиле CONSTANT_CASE: все буквы в верхнем регистре, каждое слово отделено от следующего подчеркиванием. Но что именно является константой?
Константы — это статические финальные поля, содержимое которых является неизменным, и методы, которые не имеют видимых побочных эффектов. Это относится к примитивам, String, неизменяемым типам и неизменяемым коллекциям неизменяемых типов. Если какое-либо наблюдаемое состояние объекта может измениться, он не является константой. Простого намерения никогда не изменять объект недостаточно.
Имена констант обычно являются существительными или словосочетаниями с существительными.
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», на самом деле не совсем в «верблюжьем» стиле; оно не соответствует каким-либо соглашениям, поэтому данная рекомендация не применяется.
- … в каждом слове, чтобы достичь стиля UpperCamelCase, или
- … в каждом слове, кроме первого, чтобы достичь стиля lowerCamelCase
Обратите внимание, что регистр исходных слов почти полностью игнорируется.
| Исходная форма | Правильно | Неправильно |
|---|---|---|
| «XML HTTP request» | XmlHttpRequest | XMLHTTPRequest |
| «new customer ID» | newCustomerId | newCustomerID |
| «inner stopwatch» | innerStopwatch | innerStopWatch |
| «supports IPv6 on iOS?» | supportsIpv6OnIos | supportsIPv6OnIOS |
| «YouTube importer» | YouTubeImporter YoutubeImporter* |
*Допускается, но не рекомендуется.
Примечание: некоторые слова в английском языке используют дефис неоднозначно: например, оба слова «nonempty» и «non-empty» являются правильными, поэтому имена методов checkNonempty и checkNonEmpty также являются правильными.
6. Практика программирования
6.1 Используйте всегда аннотацию @Override
Метод помечается аннотацией @Override всякий раз, когда он действительно переопределяется. Это относится как к методу класса-потомка, переопределяющему метод класса-родителя, так и к методу интерфейса, переопределяющему метод супер-интерфейса.
Исключение: аннотация может быть опущена, если родительский метод помечен аннотацией @Deprecated.
6.2 Не игнорируйте пойманные исключения
Очень редко возникают ситуации, когда не нужно предпринимать ни каких действий в ответ на пойманное исключение (типичным решением является занесение в лог или, если это считается «невозможным», перебросить исключение как AssertionError).
Ниже приведен пример с поясняющим комментарием, когда действительно уместно не предпринимать никаких действий в блоке catch:
Исключение: в тестах пойманное исключение может быть проигнорировано и не сопровождено комментарием, если именем теста является expected или же, если имя начинается с expected. Ниже приводится очень распространенная идиома, показывающая, что тестируемый код генерирует исключение ожидаемого типа, поэтому здесь комментарии не нужны:
6.3 Для статических членов используйте имя класса
Обращаться к члену статического класса необходимо через имя класса, а не по ссылке на объект класса или по выражению, возвращающему этот объект:
6.4 Не используйте финализаторы
Крайней редко необходимо переопределить метод Object.finalize.
Не делайте этого. Если вам действительно это нужно, сначала прочитайте и очень тщательно осмыслите Effective Java Item 7, «Avoid Finalizers», а затем — не делайте этого.
7. Javadoc
7.1 Форматирование
7.1.1 Основная форма
Простое форматирование блоков 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, хотя это, конечно, рекомендуется.
Как оформлять код Java
В языке программирования Java есть большой набор не совсем официальных, но все же уважаемых среди разработчиков правил и соглашений касательно оформления кода. В случае с языком Java своего рода кодекс по оформлению программ называется Java Code Style. Предлагаем более подробно рассмотреть этот кодекс и понять, почему стоит использовать его в своей работе независимо от вашего опыта.
Что такое Java Code Style
Java Code Style — это набор правил и соглашений относительно форматирования и стиля написания кода на языке программирования Java. Он определяет, как должен выглядеть код, как именовать те или иные объекты, какие комментарии следует добавлять, и так далее. Цель Java Code Style состоит в том, чтобы сделать код более читабельным, понятным и поддерживаемым.
Каждая компания или команда разработчиков может создавать собственные своды правил на базе Java Code Style. Так, Oracle определяет собственный стиль написания кода под названием «Oracle Code Conventions for the Java Programming Language». Есть другие стандарты, такие как «Google Java Style Guide» и «Sun Code Conventions». Каждый из них имеет собственные особенности и подходы к разработке, но все они стремятся к общей цели — повышению качества и читабельности кода.
Зачем нужен Java Code Style
Есть ряд причин, по которым тысячи разработчиков приложений на языке программирования Java в какой-то момент вместе пришли к консенсусу в вопросе оформления кода. Вот основные из них:
- До 80% затрат при разработке ПО приходится не на создание, а на поддержку и дальнейшее развитие кода. Если с чего читабельностью большие проблемы, расходы будут серьезные.
- Над проектом, как правило, работает несколько разработчиков в составе команды, зачастую довольно большой. Ее состав может меняться, как и любой другой рабочий коллектив. Единый стиль написания кода упрощает ввод новых специалистов в работу над проектом.
- Внесение изменений в код — лишь малая часть работы. В основном проект читают, и чтобы этот процесс был быстрым и эффективным, оформление должно быть понятным и единым.
- Поддержка проектов занимает гораздо меньше времени и усилий, когда все файлы имеют согласованный стиль оформления. В особенности это актуально для больших IT-разработок.
В конечном итоге, исходный код — продукт, который должен быть грамотно оформлен и упакован. Именно этого и помогает достичь Java Code Style. Давайте рассмотрим этот кодекс более подробно, узнаем, как оформлять код Java, писать комментарии, называть переменные и другие объекты.
Правила оформления кода Java
Вы можете найти полный кодекс Java Code Style на официальном сайте Oracle на английском языке с подробными примерами оформления кода в тех или иных ситуациях. Мы же рассмотрим главные правила и принципы коротко и доступно, так, чтобы вы смогли сразу применить их в своей работе.
Отступы и пробелы
За одну единицу отступа в языке Java принято использовать четыре пробела. Табуляция же, в свою очередь, равна восьми пробелам, а не четырем, как во многих других языках программирования.
Максимальная длина одной строки кода — 80 символов. Строки, размер которых превышает такое ограничение, зачастую обрабатываются некорректно в большинстве современных сред разработки. Для работы с документацией ограничение еще строже — не более 70 символов в одной строке кода.
Отдельная тема — переносы длинных строек. В случае, если выражение настолько длинное, что его нельзя уместить в одной строке и укоротить, можно воспользоваться переносом по правилам:
- любое выражение переносится строго после запятой и перед оператором;
- начало новой строки должно находиться на том же уровне, что и предыдущей.
В случае, если попытки перенести выражение на новую строку ухудшают читабельность кода, сразу после переноса введите 8 пробелов (одна единица табуляции). Как правило, это решает проблему.
Используйте пробелы для разделения двух и более аргументов (сразу после запятой), а также всех бинарных операторов от своих операндов за исключением точки. При этом будьте внимательны — пробел не используется для разделения инкремента, декремента и прочих унарных операторов.
Пустые строки
Для большей читабельности текста программы рекомендуем использовать пустые строки там, где это уместно. Так, две пустые строки принято устанавливать между секциями и определениями классов/интерфейсов. Одна пустая строка обязательно прописывается в перечисленных местах:
- между переменными метода и его первым по счету оператором;
- между двумя методами, расположенными друг рядом с другом;
- перед однострочным и/или блочным комментарием (об этом ниже).
Также одну пустую строку принято ставить между логическими частями кода внутри одного метода.
Наименования переменных
Переменные в языке Java именуются со строчной буквы. Если название состоит из двух или более слов, каждое из них, за исключением первого, указывают с большой буквы. Подчеркивания и тире не используются. Рекомендуется назвать переменные существительными, в том числе составными.
- правильные наименования: mailService, backDoor, louderBark;
- неправильные наименования: MailService, back-door, Louderbark.
При необходимости в названии переменных можно использовать уточняющие прилагательные.
Наименования методов
Методы именуются одним либо несколькими словами слитно без использования подчеркиваний и тире. Если название метода составное, первое слово указывают со строчной буквы, остальные — уже с заглавной. Так как метод — это действие, для его наименования принято использовать глаголы:
- правильные примеры: print (), parseText (), isScroll ();
- неправильные примеры: Print (), Parse-Text (), isscroll ().
Так как в языке программирования Java широко используются такие виды методов, как «геттеры» и «сеттеры», правила их наименования также прописаны в кодексе. В случае с геттерами название метода начинается с префикса get. Исключение — метод, взаимодействующий с переменной типа boolean. В этом случае название геттера начинается с префикса is, тем самым отвечая на вопрос.
Названия методов-сеттеров формируются так же, но вместо префикса get пишется приставка set.
Наименования классов
Классы и интерфейсы в языке Java именуются с заглавной буквы. Если имя составное, то есть в его структуре содержится два или более слова, каждое из них также прописывается с заглавной буквы. Слова в названии классов и интерфейсов указываются слитно. Тире и подчеркивания недопустимы:
- правильно: GuideBook, LastName, FullSize, BlueNumber;
- неправильно: guide_Book, lastname, Full-Size, Bluenumber.
В названии классов в языке Java принято использовать существительные. Если есть необходимость, к ним можно добавить прилагательное, которое уточняет наименование. Например, ImmutableList.
Наименование интерфейса может содержать существительные или прилагательные в случае, если речь идет о каком-либо свойстве. Что касается классов тестов, для большей читабельности кода их названия должны включать слово test на последнем месте. Примеры: SpeedTest, CrushTest и другие.
Наименования констант
В отличие от перечисленных выше примеров, названия констант оформляются в стиле SNAKE_CASE. Следовательно, все слова начинаются с заглавной буквы, а между ними ставится подчеркивание. Как и в случае с переменными, рекомендуется использовать существительные с прилагательными.
Скобки и операторы
Фигурная скобка в коде на языке программирования Java открываются на той же строке, в которой находится код перед ней. Тело условного оператора или цикла рекомендуется размещать внутри фигурных скобок даже в том случае, если код занимает всего одну строку. Это предотвратит ошибку в случае добавления второй строки без добавления фигурных скобок. Вы сэкономите себе время.
Аббревиатуры и сокращения
Использование сокращений при разработке кода нежелательно хотя бы по той причине, что другие разработчики, которые заглянут в ваш проект, не поймут, что именно вы имели ввиду. Может быть и такое, что коллеги не найдут методы и классы со стандартизированными названиями и создадут их самостоятельно. Очевидно, что это утяжелит код и даже может привести к серьезным ошибкам.
Как не стоит сокращать: int lstId вместо int lastId, class CurPage вместо class CurrentPage и так далее.
Что касается аббревиатур, их применение зачастую неизбежно, но в ваших силах сделать их более читабельными. Для этого прописывайте аббревиатуры как слово только с одной заглавной буквой. Например, не HTMLPage, а HtmlPage, не class HTTPRequest, а class HttpRequest. Это смотрится лучше.
Комментирование кода
В ходе разработки программы на языке Java возможно использование двух видов комментариев — реализации и документации. К первым относятся комментарии, которые также применяются в C++. Они обозначаются следующим образом — /*…*/ и //. Документирующие, в свою очередь, есть лишь в Java. Для их обозначения используются символы /**…*/. Особенность таких комментариев в том, что их можно извлекать из кода и отправлять в HTML-файл при помощи инструмента JavaDoc.
Комментирование можно использовать в отношении как отдельных строк, так и блоков, и даже в рамках целых алгоритмов, занимающих десятки и даже сотни строчек. Документирующие нужны в случае, когда стоит задача описать спецификацию программы (в том числе пользовательский интерфейс) вне зависимости от ее реализации. Такие комментарии пишутся в том числе для тех разработчиков, которые будут пользоваться софтом, не имея доступа к его исходному коду.
Java-разработчикам доступно четыре вида комментариев. Давайте рассмотрим их подробнее.
Блочные
Применяются для описания методов, алгоритмов, файлов и структур данных, в том числе внутри описываемых участков. Если блочный комментарий прописывается внутри метода или функции, он должен иметь аналогичный отступ.
Для визуального отделения блочного комментария от остального кода перед ним нужно оставлять пустую строку. Текст пояснения укладывается между открывающим тегом /* и закрывающим */. Каждая строка начинается символом *. Интересно, что при таком оформлении на комментарий не распространяется опция автоформатирования.
Однострочные
Однострочные комментарии оформляются так же, как и блочные, но в одну строку. Рекомендуется прописывать его с отступом на уровне комментируемого блока. Если размер пояснения слишком большой и не умещается в одну строку, необходимо использовать блочное комментирование.
Прицепные
Если комментарий очень короткий, буквально в 2−3 слова, можно расположить его прямо на строке с описываемым кодом. Чтобы пояснение не сливалось с текстом программы, нужно сдвинуть его вправо. Количество пробелов не регламентировано, главное, чтобы был контраст на фоне кода. В случае использования нескольких прицепных пояснений их начала должны быть на одном уровне.
До конца строки
С помощью символов // можно обозначить начало комментария, который продолжается вплоть до начала следующей строки. Для многострочных пояснений этот метод не подходит, но его можно использовать, когда надо закомментировать несколько строчек, например, на время отладки.
Несмотря на всю пользу и удобство комментариев, не стоит злоупотреблять их количеством. Если вы видите необходимость прокомментировать тот или иной участок программы, подумайте, можно ли отредактировать его таким образом, чтобы сделать код более читабельным и понятным.
Правила объявления
Для удобочитаемости кода рекомендуется использовать одно объявление на строку. Это не только выглядит более читабельно в сравнении с нагромождением переменных или констант, но еще и упрощает дальнейшее комментирование программы. Чего точно нельзя делать, так это объявлять переменные и функции в одной строке, как и размещать таким образом переменные разных типов.
Вы сделаете код более понятным, если будете проставлять между типом и идентификатором не один пробел, а четыре. Необязательно нажимать Space четыре раза — достаточно нажать Tab.
Размещение
Объявления переменных размещаются только в самом начале блоков, то есть участков кода между фигурными скобками < >. Пожалуй, единственным допустимым исключением из этого правила будет объявление индексов в цикле for. В этом случае они указываются непосредственно в операторе.
Инициализация
Инициализируйте локальные переменные в том же месте, в котором их объявляете. Исключение- если начальное значение данной переменной определяется предварительными вычислениями.
Инструменты для оформления кода в IDE
Чтобы сэкономить время на ручном оформлении кода, подключите правила в среде разработки, которой пользуетесь в своей работе. Тот же Google Java Style Guide, упомянутый в начале статьи, можно скачать на GitHub и подключить в IDE как модуль. После установки остается дело техники — включить автоформатирование кода и наблюдать за тем, как оформление само приходит в норму.
Несмотря на возможность автоматического соблюдения правил и соглашений Java Code Style, все же стоит запомнить их и писать код изначально в соответствии с рекомендациями разработчиков.
Даже если вы начинающий разработчик и только учитесь, рекомендуем сразу привыкать к единым стандартам оформления кода. Поверьте, это лучше, чем долго переучиваться в дальнейшем, когда трудоустроитесь в более-менее серьезную команду. Более опытным разработчикам рекомендуем ознакомиться с полной версией Java Code Style в оригинале, доступной на сайте компании Oracle.
Изучаем Java
В языке Java, как и в любом другом языке программирования, есть условные операторы и циклы для управления потоком. Начнем с условных операторов, а затем перейдем к циклам. Наш экскурс завершится довольно неуклюжим оператором switch, который можно применять при проверке большого количества значений одного выражения.
Поток управления в языке Java построен точно так же, как и в языках С и C++, за исключением двух моментов. В нем нет оператора goto, однако существует версия оператора break с метками, который можно использовать для выхода из вложенного цикла (в языке С для этого пришлось бы применять оператор goto).
Область видимости блока
Перед изучением действительно управляющих структур нам необходимо побольше узнать о блоках.
Блок, или составной оператор, — это произвольное количество простых операторов языка Java, заключенных в фигурные скобки. Блоки определяют область видимости своих переменных. Блоки могут быть вложенными один в другой. Вот пример блока, вложенного внутрь другого блока в методе main.
public static void main (string [] args) <
int n; <
…
int k;
…
> // Переменная k определена только в этом блоке.
>
Однако в языке Java невозможно объявить одинаково названные переменные в двух вложенных блоках. Например, приведенный ниже фрагмент кода содержит ошибку и не будет скомпилирован.
public static void main(Strinq[] args)
<
int n; <
…
int k;
int n; // Ошибка — невозможно переопределить переменную n во внутреннем блоке.
…
>
>
В языке C++ переменные во вложенных блоках можно переопределять. Внутреннее определение затем маскируется внешним. Это может привести к ошибкам, поэтому в языке Java такой возможности нет.
Условные операторы
Условный оператор в языке Java имеет вид:
if (условие) оператор
Условие должно указываться в скобках.
В языке Java, как и в большинстве других языков программирования, часто необходимо выполнять много операторов в зависимости от выполнения одного условия. В этом случае используется блочный оператор, имеющий следующий вид.
if (yourSales >= target)
<
performance = «Удовлетворительно» ;
bonus = 100;
>
В этом коде все операторы, заключенные в фигурные скобки, будут выполнены, если значение переменной YourSales больше значения переменной target или равно ему (рис. 3.7).
Блок (иногда называемый составным оператором) позволяет включать несколько (простых) операторов в любую структуру языка Java, которая в ином случае состояла бы лишь из одного (простого) оператора.
Рис. 3.7. Блок-схема оператора if
Более общий условный оператор в языке Java выглядит так (рис. 3.8).
if (условие) оператор1 else оператор2
if (yourSales >= target)
<
performance = «Удовлетворительно»);
bonus = 100 + 0.01 * (yourSales — target);
>
else
<
performance = «Неудовлетворительно»;
bonus = 0;
>
Часть else не является обязательной. Группы операторов else объединяются с ближайшим оператором if. Таким образом, в коде
if (х <= 0) if (х = = 0) sign = 0; else sign = -1;
оператор else соответствует второму оператору if.