В языке программирования 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.
